Skip to content
Source
Sign inSign up
Open History to see the last commit

SourceControlProvider.ts

220 lines8.5 KB

1import * as Context from "effect/Context";
2import * as Effect from "effect/Effect";
3import type * as Option from "effect/Option";
4import type {
5 RepositoryIdentity,
6 ChangeRequest,
7 ChangeRequestState,
8 SourceControlProviderError,
9 SourceControlProviderInfo,
10 SourceControlProviderKind,
11 SourceControlRepositoryCloneUrls,
12 SourceControlRepositoryVisibility,
13} from "@t3tools/contracts";
14​
15export interface SourceControlLinkSubject {
16 readonly title: string;
17 readonly body: string | null;
19​
20/** Return undefined synchronously for unsupported URLs, without starting a lookup. */
21export type ResolveSourceControlLink = (input: {
22 readonly cwd: string;
23 readonly url: URL;
24}) => Effect.Effect<SourceControlLinkSubject, SourceControlProviderError> | undefined;
25​
26export interface SourceControlProviderContext {
27 readonly provider: SourceControlProviderInfo;
28 readonly remoteName: string;
29 readonly remoteUrl: string;
30 readonly requestedHost?: string;
32​
33export interface SourceControlRefSelector {
34 readonly refName: string;
35 readonly owner?: string;
36 readonly repository?: string;
38​
39const MAX_ERROR_TRANSPORT_VALUE_LENGTH = 256;
40​
41/**
42 * The fixed product text a provider failure carries for the user, if it has one. Any other
43 * detail may be upstream response text, so callers show a generic message instead.
44 */
45export function userFacingSourceControlDetail(cause: unknown): string | undefined {
46 return typeof cause === "object" &&
47 cause !== null &&
48 "userFacingDetail" in cause &&
49 typeof cause.userFacingDetail === "string"
50 ? cause.userFacingDetail
51 : undefined;
53​
54export function transportSafeSourceControlErrorValue(value: string): string {
55 let printable = "";
56 for (const character of value) {
57 const codePoint = character.codePointAt(0);
58 printable += codePoint !== undefined && (codePoint < 32 || codePoint === 127) ? " " : character;
59 }
60 const normalized = printable.trim().replace(/\s+/gu, " ");
61​
62 let safe = normalized;
63 try {
64 const url = new URL(normalized);
65 url.username = "";
66 url.password = "";
67 url.search = "";
68 url.hash = "";
69 safe = url.toString();
70 } catch {}
71​
72 return safe.slice(0, MAX_ERROR_TRANSPORT_VALUE_LENGTH);
74​
75export function parseSourceControlOwnerRef(
76 headSelector: string,
77): SourceControlRefSelector | undefined {
78 const match = /^([^:/\s]+):(.+)$/u.exec(headSelector.trim());
79 const owner = match?.[1]?.trim();
80 const refName = match?.[2]?.trim();
81 return owner && refName ? { owner, refName } : undefined;
83​
84function normalizeSourceBranch(headSelector: string): string {
85 return parseSourceControlOwnerRef(headSelector)?.refName ?? headSelector.trim();
87​
88export function sourceBranch(input: {
89 readonly headSelector: string;
90 readonly source?: SourceControlRefSelector;
91}): string {
92 return input.source?.refName ?? normalizeSourceBranch(input.headSelector);
94​
95export function sourceControlRefFromInput(input: {
96 readonly headSelector: string;
97 readonly source?: SourceControlRefSelector;
98}): SourceControlRefSelector | undefined {
99 return input.source ?? parseSourceControlOwnerRef(input.headSelector);
101​
102export function repositoryPathFromRemoteUrl(url: string | null): string | null {
103 const remote = url?.trim() ?? "";
104 const trimmed = /^(?:ssh|https?|git):\/\//iu.test(remote) ? remote.split(/[?#]/u, 1)[0]! : remote;
105 if (trimmed.length === 0) {
106 return null;
107 }
108​
109 const match =
110 /^(?:[^@/\s]+@[^:/\s]+:|[^@:/\\\s]{2,}:(?!:)|(?:ssh|https?|git):\/\/[^/]+\/)((?:[^/\s]+\/)+[^/\s]+?)(?:\.git)?\/?$/iu.exec(
111 trimmed,
112 );
113 const path = match?.[1]?.trim() ?? "";
114 return path.length > 0 ? path : null;
116​
117export class SourceControlProvider extends Context.Service<
118 SourceControlProvider,
119 {
120 readonly kind: SourceControlProviderKind;
121 /** The caller verifies owners, so hosts may drop unsupported `owner:branch` selectors. */
122 readonly headBranchProbe?: (input: {
123 readonly headSelectors: ReadonlyArray<string>;
124 readonly state: "open" | "all";
125 /** `owner:branch` when the head is the default branch, a name most forks share. */
126 readonly defaultBranchHeadSelector?: string | undefined;
127 }) => { readonly headSelectors: ReadonlyArray<string>; readonly limit: number };
128 readonly readChangeRequestTemplate?: (input: {
129 readonly cwd: string;
130 readonly treeish: string;
131 }) => Effect.Effect<Option.Option<string>>;
132 /** Strip installation mounts from remote paths; absent means use the whole path. */
133 readonly repositoryNameFromRemoteUrl?: (url: string) => string | null;
134 readonly refineRepositoryIdentity?: (input: {
135 readonly identity: RepositoryIdentity;
136 readonly resolveContext: (input: {
137 readonly cwd: string;
138 readonly context: SourceControlProviderContext;
139 }) => Effect.Effect<SourceControlProviderContext | null, SourceControlProviderError>;
140 }) => Effect.Effect<RepositoryIdentity, SourceControlProviderError>;
141 /**
142 * The web host serving a remote, for a host whose remote URL may not name it (an SSH alias
143 * for one of several servers). It answers for the context's `requestedHost` when the caller
144 * narrows to one. Absent, or null, means the remote's own host is the web host.
145 */
146 readonly resolveRemoteWebHost?: (input: {
147 readonly cwd: string;
148 readonly context: SourceControlProviderContext;
149 readonly resolveContext: (input: {
150 readonly cwd: string;
151 readonly context: SourceControlProviderContext;
152 }) => Effect.Effect<SourceControlProviderContext | null, SourceControlProviderError>;
153 }) => Effect.Effect<string | null, SourceControlProviderError>;
154 readonly resolveLink?: ResolveSourceControlLink;
155 /**
156 * Whether `createChangeRequest` from `cwd` targets `repository`, the `owner/name` of the
157 * context's remote, for a host whose tools let configuration outside the remotes name another
158 * repository. Absent means it does.
159 */
160 readonly createsChangeRequestsIn?: (input: {
161 readonly cwd: string;
162 readonly context: SourceControlProviderContext;
163 readonly repository: string | null;
164 }) => Effect.Effect<boolean>;
165 /**
166 * Told when T3 records `baseBranch`, a branch name on the host, as the base `branch` was cut
167 * from, for a host whose own tools keep that in git config of their own.
168 */
169 readonly recordBranchBase?: (input: {
170 readonly cwd: string;
171 readonly branch: string;
172 readonly baseBranch: string;
173 }) => Effect.Effect<void>;
174 readonly listChangeRequests: (input: {
175 readonly cwd: string;
176 readonly context?: SourceControlProviderContext;
177 readonly source?: SourceControlRefSelector;
178 readonly headSelector: string;
179 readonly state: ChangeRequestState | "all";
180 readonly limit?: number;
181 }) => Effect.Effect<ReadonlyArray<ChangeRequest>, SourceControlProviderError>;
182 readonly getChangeRequest: (input: {
183 readonly cwd: string;
184 readonly context?: SourceControlProviderContext;
185 readonly reference: string;
186 }) => Effect.Effect<ChangeRequest, SourceControlProviderError>;
187 readonly createChangeRequest: (input: {
188 readonly cwd: string;
189 readonly context?: SourceControlProviderContext;
190 readonly source?: SourceControlRefSelector;
191 readonly target?: SourceControlRefSelector;
192 readonly baseRefName: string;
193 readonly headSelector: string;
194 readonly title: string;
195 readonly bodyFile: string;
196 }) => Effect.Effect<void, SourceControlProviderError>;
197 readonly getRepositoryCloneUrls: (input: {
198 readonly cwd: string;
199 readonly context?: SourceControlProviderContext;
200 readonly repository: string;
201 /** The host the repository is on. Without it, the checkout's host. */
202 readonly host?: string;
203 }) => Effect.Effect<SourceControlRepositoryCloneUrls, SourceControlProviderError>;
204 readonly createRepository: (input: {
205 readonly cwd: string;
206 readonly repository: string;
207 readonly visibility: SourceControlRepositoryVisibility;
208 }) => Effect.Effect<SourceControlRepositoryCloneUrls, SourceControlProviderError>;
209 readonly getDefaultBranch: (input: {
210 readonly cwd: string;
211 readonly context?: SourceControlProviderContext;
212 }) => Effect.Effect<string | null, SourceControlProviderError>;
213 readonly checkoutChangeRequest: (input: {
214 readonly cwd: string;
215 readonly context?: SourceControlProviderContext;
216 readonly reference: string;
217 readonly force?: boolean;
218 }) => Effect.Effect<void, SourceControlProviderError>;
219 }
220>()("@t3tools/source-control-core/server/SourceControlProvider") {}