forges 0.0.0 → 0.1.0

package/dist/schema/ReleaseAssetRef.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "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"
+    },
+    "release": {
+      "$ref": "#/definitions/ReleaseRef"
+    },
+    "id": {
+      "type": "string",
+      "description": "Forge-native asset id; the asset name, or the link id, on forges that have no asset id."
+    }
+  },
+  "required": [
+    "forge",
+    "id",
+    "instance",
+    "release",
+    "repo"
+  ],
+  "description": "A release asset, addressable for download with `releases.downloadAsset`.",
+  "x-forges-type": "ReleaseAssetRef",
+  "definitions": {
+    "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"
+    },
+    "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"
+    }
+  }
+}

package/dist/schema/ReleaseRef.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "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",
+  "definitions": {
+    "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"
+    },
+    "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"
+    }
+  }
+}

package/dist/schema/Repo.json

@@ -0,0 +1,354 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "ref": {
+      "$ref": "#/definitions/RepoRef"
+    },
+    "displayName": {
+      "type": "string",
+      "description": "The repository's name where `ref.name` is an identifier rather than the name (a Tangled record key)."
+    },
+    "description": {
+      "type": "string"
+    },
+    "defaultBranch": {
+      "type": "string"
+    },
+    "visibility": {
+      "$ref": "#/definitions/RepoVisibility",
+      "description": "Who can see the repository."
+    },
+    "visibilityRaw": {
+      "type": "string"
+    },
+    "isFork": {
+      "type": "boolean"
+    },
+    "isArchived": {
+      "type": "boolean",
+      "description": "The repository is archived and read-only."
+    },
+    "parent": {
+      "$ref": "#/definitions/RepoRef",
+      "description": "The repository that this one was forked from."
+    },
+    "topics": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Topics, also called tags, that describe the repository."
+    },
+    "url": {
+      "type": "string"
+    },
+    "cloneUrls": {
+      "type": "object",
+      "properties": {
+        "https": {
+          "type": "string"
+        },
+        "ssh": {
+          "type": "string"
+        }
+      },
+      "description": "Git remotes. Tangled maps the hosting knot to its SSH host."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "pushedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Last push, where the listing endpoint reports it."
+    },
+    "openIssueCount": {
+      "type": "number",
+      "description": "Open issues only, never combined with pull requests. Absent where the forge reports only the combined count (GitHub)."
+    },
+    "openPullCount": {
+      "type": "number",
+      "description": "The number of open pull requests, where the forge reports it."
+    },
+    "owner": {
+      "$ref": "#/definitions/Actor",
+      "description": "The account or organisation that owns the repository, where the forge reports one."
+    },
+    "language": {
+      "type": "string",
+      "description": "Primary language, as the forge detects it."
+    },
+    "homepage": {
+      "type": "string",
+      "description": "Project website, apart from the repository's own `url`."
+    },
+    "licence": {
+      "type": "string",
+      "description": "SPDX identifier of the licence the forge detects, for example `MIT`. SPDX identifiers are case-insensitive, and GitLab reports them in lower case, such as `mit`."
+    },
+    "stars": {
+      "type": "number"
+    },
+    "forks": {
+      "type": "number"
+    },
+    "watchers": {
+      "type": "number",
+      "description": "Accounts watching the repository's activity, apart from stars."
+    },
+    "permissions": {
+      "$ref": "#/definitions/RepoPermissions",
+      "description": "What the authenticated account may do."
+    },
+    "mergeMethods": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/MergeMethod"
+      },
+      "description": "Merge methods the repository allows, where the forge reports them. Empty means the forge reported none."
+    },
+    "features": {
+      "$ref": "#/definitions/RepoFeatures"
+    },
+    "raw": {}
+  },
+  "required": [
+    "ref",
+    "visibility",
+    "isFork",
+    "isArchived",
+    "topics",
+    "raw"
+  ],
+  "description": "A repository as every forge reports it. Fields that not every forge has, such as `openPullCount`, are optional.",
+  "x-forges-type": "Repo",
+  "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"
+    },
+    "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"
+    },
+    "MergeMethod": {
+      "type": "string",
+      "enum": [
+        "merge",
+        "squash",
+        "rebase",
+        "rebase_merge",
+        "fast_forward_only"
+      ],
+      "description": "How a pull request is merged.",
+      "x-forges-type": "MergeMethod"
+    },
+    "RepoFeatures": {
+      "type": "object",
+      "properties": {
+        "issues": {
+          "type": "boolean"
+        },
+        "pullRequests": {
+          "type": "boolean"
+        },
+        "discussions": {
+          "type": "boolean"
+        },
+        "wiki": {
+          "type": "boolean"
+        },
+        "projects": {
+          "type": "boolean"
+        },
+        "releases": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "issues",
+        "pullRequests",
+        "discussions",
+        "wiki",
+        "projects",
+        "releases"
+      ],
+      "description": "Which subjects a repository has switched on, where the forge makes them per repository.",
+      "x-forges-type": "RepoFeatures"
+    },
+    "RepoPermissions": {
+      "type": "object",
+      "properties": {
+        "admin": {
+          "type": "boolean",
+          "description": "Full administrative access."
+        },
+        "maintain": {
+          "type": "boolean",
+          "description": "Manage the repository without access to sensitive or destructive settings."
+        },
+        "push": {
+          "type": "boolean"
+        },
+        "triage": {
+          "type": "boolean",
+          "description": "Manage issues and pull requests without write access."
+        },
+        "pull": {
+          "type": "boolean",
+          "description": "Read and clone the repository."
+        }
+      },
+      "required": [
+        "admin",
+        "maintain",
+        "push",
+        "triage",
+        "pull"
+      ],
+      "description": "The authenticated account's access to a repository.",
+      "x-forges-type": "RepoPermissions"
+    },
+    "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"
+    },
+    "RepoVisibility": {
+      "type": "string",
+      "enum": [
+        "public",
+        "private",
+        "internal"
+      ],
+      "description": "Who can see a repository.",
+      "x-forges-type": "RepoVisibility"
+    }
+  }
+}

package/dist/schema/RepoFeatures.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "issues": {
+      "type": "boolean"
+    },
+    "pullRequests": {
+      "type": "boolean"
+    },
+    "discussions": {
+      "type": "boolean"
+    },
+    "wiki": {
+      "type": "boolean"
+    },
+    "projects": {
+      "type": "boolean"
+    },
+    "releases": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "issues",
+    "pullRequests",
+    "discussions",
+    "wiki",
+    "projects",
+    "releases"
+  ],
+  "description": "Which subjects a repository has switched on, where the forge makes them per repository.",
+  "x-forges-type": "RepoFeatures",
+  "definitions": {}
+}

package/dist/schema/RepoPermissions.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "admin": {
+      "type": "boolean",
+      "description": "Full administrative access."
+    },
+    "maintain": {
+      "type": "boolean",
+      "description": "Manage the repository without access to sensitive or destructive settings."
+    },
+    "push": {
+      "type": "boolean"
+    },
+    "triage": {
+      "type": "boolean",
+      "description": "Manage issues and pull requests without write access."
+    },
+    "pull": {
+      "type": "boolean",
+      "description": "Read and clone the repository."
+    }
+  },
+  "required": [
+    "admin",
+    "maintain",
+    "push",
+    "triage",
+    "pull"
+  ],
+  "description": "The authenticated account's access to a repository.",
+  "x-forges-type": "RepoPermissions",
+  "definitions": {}
+}