forges 0.0.0 → 0.1.0

package/dist/schema/EventDetail.json

@@ -0,0 +1,649 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "anyOf": [
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "comment"
+        },
+        "comment": {
+          "$ref": "#/definitions/CommentRef"
+        },
+        "body": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "review_comment"
+        },
+        "comment": {
+          "$ref": "#/definitions/CommentRef"
+        },
+        "body": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        },
+        "line": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "review"
+        },
+        "state": {
+          "$ref": "#/definitions/ReviewState"
+        },
+        "stateRaw": {
+          "type": "string"
+        },
+        "body": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "state"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "state_change"
+        },
+        "state": {
+          "$ref": "#/definitions/ThreadState"
+        },
+        "draft": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "label"
+        },
+        "label": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "label"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "assignment"
+        },
+        "assignee": {
+          "$ref": "#/definitions/Actor"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "push"
+        },
+        "ref": {
+          "type": "string"
+        },
+        "before": {
+          "type": "string"
+        },
+        "after": {
+          "type": "string"
+        },
+        "commitCount": {
+          "type": "number"
+        },
+        "forced": {
+          "type": "boolean"
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PushCommit"
+          }
+        }
+      },
+      "required": [
+        "type",
+        "ref",
+        "commitCount",
+        "forced",
+        "commits"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "ref"
+        },
+        "ref": {
+          "type": "string"
+        },
+        "refType": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "ref",
+        "refType"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "repo_renamed"
+        },
+        "from": {
+          "type": "string"
+        },
+        "to": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "from",
+        "to"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "repo_transferred"
+        },
+        "fromOwner": {
+          "type": "string"
+        },
+        "toOwner": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "repo_archived"
+        },
+        "archived": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "type",
+        "archived"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "installation"
+        },
+        "actionRaw": {
+          "type": "string"
+        },
+        "installationId": {
+          "type": "string"
+        },
+        "added": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RepoRef"
+          }
+        },
+        "removed": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RepoRef"
+          }
+        }
+      },
+      "required": [
+        "type",
+        "actionRaw",
+        "added",
+        "removed"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "membership"
+        },
+        "actionRaw": {
+          "type": "string"
+        },
+        "member": {
+          "$ref": "#/definitions/Actor"
+        }
+      },
+      "required": [
+        "type",
+        "actionRaw"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "release"
+        },
+        "release": {
+          "$ref": "#/definitions/ReleaseRef"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "release"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "referenced"
+        },
+        "from": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ThreadRef"
+            },
+            {
+              "$ref": "#/definitions/CommitRef"
+            }
+          ]
+        },
+        "fromRepo": {
+          "$ref": "#/definitions/RepoRef"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    }
+  ],
+  "description": "Typed detail for an event. Discriminated by `type`.",
+  "x-forges-type": "EventDetail",
+  "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"
+    },
+    "CommentRef": {
+      "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`."
+        },
+        "thread": {
+          "$ref": "#/definitions/ThreadRef"
+        },
+        "id": {
+          "type": "string",
+          "description": "Forge-native comment id; an AT-URI on Tangled."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "thread"
+      ],
+      "description": "Reference to a comment on a thread.",
+      "x-forges-type": "CommentRef"
+    },
+    "CommitRef": {
+      "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"
+        },
+        "sha": {
+          "type": "string",
+          "description": "The full sha of the commit."
+        }
+      },
+      "required": [
+        "forge",
+        "instance",
+        "repo",
+        "sha"
+      ],
+      "description": "A commit addressed by its full sha.",
+      "x-forges-type": "CommitRef"
+    },
+    "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"
+    },
+    "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"
+    },
+    "PushCommit": {
+      "type": "object",
+      "properties": {
+        "sha": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "author": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "sha"
+      ],
+      "description": "A commit as a push delivery reports it.",
+      "x-forges-type": "PushCommit"
+    },
+    "ReleaseRef": {
+      "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"
+        },
+        "id": {
+          "type": "string",
+          "description": "Forge-native release id; the tag name on forges that key releases by tag."
+        },
+        "tag": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "repo"
+      ],
+      "description": "A release, as a notification subject or event target.",
+      "x-forges-type": "ReleaseRef"
+    },
+    "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"
+    },
+    "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"
+    },
+    "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/EventKind.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "enum": [
+    "comment",
+    "review",
+    "review_comment",
+    "commit",
+    "label",
+    "state_change",
+    "assignment",
+    "mention",
+    "referenced",
+    "reaction",
+    "push",
+    "ref",
+    "repo",
+    "installation",
+    "membership",
+    "release",
+    "other"
+  ],
+  "description": "What an event is about.",
+  "x-forges-type": "EventKind",
+  "definitions": {}
+}