forges 0.0.0 → 0.1.0

package/dist/schema/Branch.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "sha": {
+      "type": "string",
+      "description": "The commit that the branch points at."
+    },
+    "isDefault": {
+      "type": "boolean"
+    },
+    "isProtected": {
+      "type": "boolean"
+    },
+    "url": {
+      "type": "string"
+    },
+    "raw": {}
+  },
+  "required": [
+    "name",
+    "sha",
+    "raw"
+  ],
+  "description": "A branch of a repository.",
+  "x-forges-type": "Branch",
+  "definitions": {}
+}

package/dist/schema/ChangedFile.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string"
+    },
+    "previousPath": {
+      "type": "string",
+      "description": "Path before a rename or copy."
+    },
+    "status": {
+      "$ref": "#/definitions/FileStatus"
+    },
+    "statusRaw": {
+      "type": "string"
+    },
+    "additions": {
+      "type": "number"
+    },
+    "deletions": {
+      "type": "number"
+    },
+    "patch": {
+      "type": "string",
+      "description": "Unified diff for the file, where the forge returns one inline."
+    },
+    "sha": {
+      "type": "string",
+      "description": "Blob sha after the change."
+    },
+    "isBinary": {
+      "type": "boolean",
+      "description": "The file is binary, so it has no patch."
+    }
+  },
+  "required": [
+    "path",
+    "status"
+  ],
+  "description": "A file that a commit or pull request changed.",
+  "x-forges-type": "ChangedFile",
+  "definitions": {
+    "FileStatus": {
+      "type": "string",
+      "enum": [
+        "added",
+        "modified",
+        "removed",
+        "renamed",
+        "copied",
+        "changed"
+      ],
+      "description": "How a commit or pull request changed a file.",
+      "x-forges-type": "FileStatus"
+    }
+  }
+}

package/dist/schema/Check.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "ref": {
+      "$ref": "#/definitions/CheckRef"
+    },
+    "name": {
+      "type": "string"
+    },
+    "state": {
+      "$ref": "#/definitions/CheckState"
+    },
+    "stateRaw": {
+      "type": "string",
+      "description": "Forge-native status, for example `in_progress` or `running`."
+    },
+    "conclusionRaw": {
+      "type": "string",
+      "description": "Forge-native conclusion, where the forge reports one apart from the status."
+    },
+    "url": {
+      "type": "string"
+    },
+    "startedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "raw": {}
+  },
+  "required": [
+    "ref",
+    "name",
+    "state",
+    "stateRaw",
+    "raw"
+  ],
+  "description": "One check on a commit: a check run, a commit status, a job or a policy evaluation.",
+  "x-forges-type": "Check",
+  "definitions": {
+    "CheckRef": {
+      "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"
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "check_run",
+            "status",
+            "job",
+            "policy"
+          ],
+          "description": "What the id addresses: a check run, a commit status, a CI job, or a branch policy evaluation."
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "repo",
+        "type"
+      ],
+      "description": "One check run, commit status or CI job.",
+      "x-forges-type": "CheckRef"
+    },
+    "CheckState": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "success",
+        "failure",
+        "neutral",
+        "unknown"
+      ],
+      "description": "`neutral` covers skipped and informational results, which neither pass nor fail.",
+      "x-forges-type": "CheckState"
+    },
+    "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/CheckRef.json

@@ -0,0 +1,114 @@
+{
+  "$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"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "check_run",
+        "status",
+        "job",
+        "policy"
+      ],
+      "description": "What the id addresses: a check run, a commit status, a CI job, or a branch policy evaluation."
+    }
+  },
+  "required": [
+    "forge",
+    "id",
+    "instance",
+    "repo",
+    "type"
+  ],
+  "description": "One check run, commit status or CI job.",
+  "x-forges-type": "CheckRef",
+  "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/CheckState.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "enum": [
+    "pending",
+    "success",
+    "failure",
+    "neutral",
+    "unknown"
+  ],
+  "description": "`neutral` covers skipped and informational results, which neither pass nor fail.",
+  "x-forges-type": "CheckState",
+  "definitions": {}
+}

package/dist/schema/ChecksSummary.json

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

package/dist/schema/CiJob.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "ref": {
+      "$ref": "#/definitions/CiJobRef"
+    },
+    "name": {
+      "type": "string"
+    },
+    "state": {
+      "$ref": "#/definitions/CheckState"
+    },
+    "stateRaw": {
+      "type": "string"
+    },
+    "stage": {
+      "type": "string",
+      "description": "Stage or group the job belongs to, where the forge has one."
+    },
+    "url": {
+      "type": "string"
+    },
+    "startedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "completedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "raw": {}
+  },
+  "required": [
+    "ref",
+    "name",
+    "state",
+    "stateRaw",
+    "raw"
+  ],
+  "description": "One job of a CI run.",
+  "x-forges-type": "CiJob",
+  "definitions": {
+    "CheckState": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "success",
+        "failure",
+        "neutral",
+        "unknown"
+      ],
+      "description": "`neutral` covers skipped and informational results, which neither pass nor fail.",
+      "x-forges-type": "CheckState"
+    },
+    "CiJobRef": {
+      "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"
+        },
+        "run": {
+          "$ref": "#/definitions/CiRunRef"
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "repo"
+      ],
+      "description": "One job inside a run. `run` is absent when the job was addressed on its own.",
+      "x-forges-type": "CiJobRef"
+    },
+    "CiRunRef": {
+      "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"
+        }
+      },
+      "required": [
+        "forge",
+        "id",
+        "instance",
+        "repo"
+      ],
+      "description": "A CI run: a workflow run, a pipeline, or a build.",
+      "x-forges-type": "CiRunRef"
+    },
+    "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"
+    }
+  }
+}