|
| 1 | +/** |
| 2 | + * The client half of a source control host package. |
| 3 | + * |
| 4 | + * Every host package exports a `SourceControlClientDefinition` from its `./client/definition` |
| 5 | + * entry point, the way `./server/driver` is its server entry. Web, mobile, and client-runtime |
| 6 | + * read labels, change request nouns, picker copy, and checkout commands from these definitions, |
| 7 | + * so a new host needs no per-kind branches in client code. |
| 8 | + * |
| 9 | + * Definitions are browser- and React Native-safe: plain data and pure functions, no server or |
| 10 | + * platform UI imports. |
| 11 | + * |
| 12 | + * @module source-control-core/client/definition |
| 13 | + */ |
| 14 | +import { type PullRequestReviewVerdict, SourceControlProviderKind } from "@t3tools/contracts"; |
| 15 | + |
| 16 | +/** What a host calls a change request, e.g. `MR` and `merge request` on GitLab. */ |
| 17 | +export interface ChangeRequestTerminology { |
| 18 | + readonly shortLabel: string; |
| 19 | + readonly singular: string; |
| 20 | +} |
| 21 | + |
| 22 | +/** Where a project's repository lives, for building its change request URLs. */ |
| 23 | +export interface ChangeRequestUrlInput { |
| 24 | + /** The host below which the repository is addressed, as `pullRequestHostOf` reports it. */ |
| 25 | + readonly host: string; |
| 26 | + /** The repository path below the host. */ |
| 27 | + readonly repository: string; |
| 28 | + readonly number: number; |
| 29 | + /** The checkout's remote URL, whose origin some hosts serve their web pages from. */ |
| 30 | + readonly remoteUrl?: string | undefined; |
| 31 | + /** The repository's browser URL, when the server resolved one from a hosting account. */ |
| 32 | + readonly webUrl?: string | undefined; |
| 33 | +} |
| 34 | + |
| 35 | +/** The change request a checkout command is built for. */ |
| 36 | +export interface ChangeRequestCheckoutInput { |
| 37 | + readonly number: number; |
| 38 | + readonly headBranch: string; |
| 39 | + readonly headRepositoryNameWithOwner?: string | null | undefined; |
| 40 | + /** The repository's web URL, for hosts whose checkout fetches from it. */ |
| 41 | + readonly repositoryUrl?: string | null | undefined; |
| 42 | +} |
| 43 | + |
| 44 | +export interface SourceControlClientDefinition { |
| 45 | + readonly kind: SourceControlProviderKind; |
| 46 | + /** The host's name, as in "Open on GitHub". */ |
| 47 | + readonly label: string; |
| 48 | + /** How the clone and publish pickers name the host; Forgejo's covers Gitea too. */ |
| 49 | + readonly pickerLabel: string; |
| 50 | + /** Glyph key each client maps to its own icon; a key a client lacks draws the generic glyph. */ |
| 51 | + readonly icon: string; |
| 52 | + readonly changeRequest: ChangeRequestTerminology; |
| 53 | + /** Placeholder for a repository path on this host, such as `owner/repo`. */ |
| 54 | + readonly repositoryPathHint: string; |
| 55 | + /** |
| 56 | + * The hostname a change request reference can be attributed to before any repository |
| 57 | + * identity is known, or null when a hostname alone does not name this host. |
| 58 | + */ |
| 59 | + readonly publicHost: string | null; |
| 60 | + /** Subtitle beside the host in the publish picker. */ |
| 61 | + readonly publishDescription: string; |
| 62 | + /** Where a publish lands, given the host the server is signed in to, if it reported one. */ |
| 63 | + readonly publishHost: (signedInHost: string | null) => string; |
| 64 | + /** Which of a repository's clone URLs a new clone uses. */ |
| 65 | + readonly defaultCloneTransport: "https" | "ssh"; |
| 66 | + /** The web URL of a change request, or null when this client cannot build one for the host. */ |
| 67 | + readonly changeRequestUrl: (input: ChangeRequestUrlInput) => string | null; |
| 68 | + /** A shell command that checks the change request out, or null when it cannot be built. */ |
| 69 | + readonly checkoutCommand: (changeRequest: ChangeRequestCheckoutInput) => string | null; |
| 70 | + /** A comment author's profile page, or null where the host has none clients can link. */ |
| 71 | + readonly authorProfileUrl: (login: string, repositoryUrl: string) => string | null; |
| 72 | + /** |
| 73 | + * The repository URL that `#123` and commit SHAs in change request text link under, using |
| 74 | + * GitHub's `/issues/` and `/commit/` routes, or null where the host does not route them so. |
| 75 | + */ |
| 76 | + readonly referenceAutolinkRepositoryUrl: (repositoryUrl: string) => string | null; |
| 77 | + /** Whether a review with this verdict must carry a summary, beyond what every host asks. */ |
| 78 | + readonly reviewSummaryRequired: (verdict: PullRequestReviewVerdict) => boolean; |
| 79 | + /** Whether a change request URL has this host's path shape, e.g. GitLab's `/-/merge_requests/`. */ |
| 80 | + readonly isChangeRequestUrl: (url: string) => boolean; |
| 81 | +} |
| 82 | + |
| 83 | +export function defineSourceControlClient<const Definition extends SourceControlClientDefinition>( |
| 84 | + definition: Definition, |
| 85 | +): Definition { |
| 86 | + return definition; |
| 87 | +} |
| 88 | + |
| 89 | +/** What clients show for a host they ship no definition for, including `unknown`. */ |
| 90 | +const UNKNOWN_SOURCE_CONTROL_CLIENT: SourceControlClientDefinition = { |
| 91 | + kind: SourceControlProviderKind.make("unknown"), |
| 92 | + label: "source control", |
| 93 | + pickerLabel: "source control", |
| 94 | + icon: "change-request", |
| 95 | + changeRequest: { shortLabel: "change request", singular: "change request" }, |
| 96 | + repositoryPathHint: "URL", |
| 97 | + publicHost: null, |
| 98 | + publishDescription: "Your signed-in server", |
| 99 | + publishHost: (signedInHost) => signedInHost ?? "your server", |
| 100 | + defaultCloneTransport: "ssh", |
| 101 | + changeRequestUrl: () => null, |
| 102 | + checkoutCommand: () => null, |
| 103 | + authorProfileUrl: () => null, |
| 104 | + referenceAutolinkRepositoryUrl: () => null, |
| 105 | + reviewSummaryRequired: () => false, |
| 106 | + isChangeRequestUrl: () => false, |
| 107 | +}; |
| 108 | + |
| 109 | +/** The host definitions a client loaded. */ |
| 110 | +export interface SourceControlClientRegistry { |
| 111 | + readonly definitions: ReadonlyArray<SourceControlClientDefinition>; |
| 112 | + /** |
| 113 | + * The definition for a kind. No kind at all, before a repository reports its host, reads as |
| 114 | + * the first definition; a kind this client lacks, `unknown` included, reads as |
| 115 | + * `UNKNOWN_SOURCE_CONTROL_CLIENT`. |
| 116 | + */ |
| 117 | + readonly get: (kind: string | null | undefined) => SourceControlClientDefinition; |
| 118 | + /** The definition for a kind, or `undefined` for one this client lacks. */ |
| 119 | + readonly find: (kind: string) => SourceControlClientDefinition | undefined; |
| 120 | + /** The definition whose public instance is `hostname`, if any. */ |
| 121 | + readonly findByPublicHost: (hostname: string) => SourceControlClientDefinition | undefined; |
| 122 | + /** The definition whose change request path shape `url` has, if any. */ |
| 123 | + readonly findByChangeRequestUrl: (url: string) => SourceControlClientDefinition | undefined; |
| 124 | + /** The name of the host a change request URL is on, for copy about that change request. */ |
| 125 | + readonly hostLabelForChangeRequestUrl: (url: string) => string; |
| 126 | +} |
| 127 | + |
| 128 | +export function makeSourceControlClientRegistry( |
| 129 | + definitions: ReadonlyArray<SourceControlClientDefinition>, |
| 130 | +): SourceControlClientRegistry { |
| 131 | + const byKind = new Map<string, SourceControlClientDefinition>(); |
| 132 | + for (const definition of definitions) { |
| 133 | + if (byKind.has(definition.kind)) { |
| 134 | + throw new Error(`Source control host '${definition.kind}' is defined more than once.`); |
| 135 | + } |
| 136 | + byKind.set(definition.kind, definition); |
| 137 | + } |
| 138 | + return { |
| 139 | + definitions, |
| 140 | + get: (kind) => (kind ? byKind.get(kind) : definitions[0]) ?? UNKNOWN_SOURCE_CONTROL_CLIENT, |
| 141 | + find: (kind) => byKind.get(kind), |
| 142 | + findByPublicHost: (hostname) => { |
| 143 | + const host = hostname.toLowerCase(); |
| 144 | + return definitions.find((definition) => definition.publicHost === host); |
| 145 | + }, |
| 146 | + findByChangeRequestUrl: (url) => |
| 147 | + definitions.find((definition) => definition.isChangeRequestUrl(url)), |
| 148 | + hostLabelForChangeRequestUrl: (url) => |
| 149 | + definitions.find((definition) => definition.isChangeRequestUrl(url))?.label ?? "the host", |
| 150 | + }; |
| 151 | +} |
0 commit comments