forges 0.0.0 → 0.1.0

package/dist/provider-Ed1YhkQN.mjs

@@ -0,0 +1,169 @@
+import { d as forgeIterable, j as toWarning, kt as UnknownForgeError } from "./define-D3yEXtKK.mjs";
+//#region src/provider.ts
+/** Items without the sorted timestamp sort last within a page and are yielded as soon as they lead it. */
+function mergeByTime(providers, verb, query, read) {
+	const order = {
+		sort: query.sort === "created" ? "created" : "updated",
+		direction: query.direction === "asc" ? "asc" : "desc"
+	};
+	const sign = order.direction === "asc" ? 1 : -1;
+	const rank = (item, missing) => {
+		const time = (order.sort === "created" ? item.createdAt : item.updatedAt)?.getTime();
+		return time === void 0 ? missing : sign * time;
+	};
+	return forgeIterable(async function* (warn) {
+		const sources = providers.filter((provider) => provider.can(verb)).map((provider) => ({
+			provider,
+			items: [],
+			done: false
+		}));
+		async function fill(source) {
+			while (!source.items.length && !source.done) try {
+				const page = await read(source.provider, {
+					...query,
+					...order,
+					cursor: source.cursor
+				});
+				page.warnings?.forEach(warn);
+				source.items = page.items.toSorted((a, b) => rank(a, Infinity) - rank(b, Infinity) || 0);
+				source.cursor = page.cursor;
+				source.done = !page.cursor?.nextUrl && !page.cursor?.token;
+			} catch (error) {
+				warn(toWarning("search_failed", error, `${source.provider.forge}:${source.provider.instance}`));
+				source.done = true;
+			}
+		}
+		await Promise.all(sources.map(fill));
+		while (true) {
+			let next;
+			let best = Infinity;
+			for (const source of sources) {
+				const head = source.items[0];
+				if (!head) continue;
+				const key = rank(head, -Infinity);
+				if (!next || key < best) {
+					next = source;
+					best = key;
+				}
+			}
+			if (!next) return;
+			yield next.items.shift();
+			await fill(next);
+		}
+	});
+}
+/**
+* Combines providers into a registry. Pass factories such as `github()`, or providers that already exist.
+* @param factories Factories such as `github()`, or providers that already exist.
+* @example
+* ```ts
+* import { createForges, github, gitlab } from 'forges'
+*
+* const forges = createForges([
+*   github({ auth: { type: 'token', token: process.env.GITHUB_TOKEN! } }),
+*   gitlab(),
+* ])
+*
+* const repo = await forges.repos.get({ forge: 'github', instance: 'github.com', owner: 'danielroe', name: 'forges' })
+* ```
+*/
+function createForges(factories) {
+	const providers = factories.map((factory) => "create" in factory ? factory.create() : factory);
+	const seen = /* @__PURE__ */ new Set();
+	for (const provider of providers) {
+		const key = `${provider.forge}:${provider.instance}`;
+		if (seen.has(key)) throw new TypeError(`Two providers are registered for ${provider.forge} on ${provider.instance}; pass \`instance\` to tell them apart`);
+		seen.add(key);
+	}
+	const find = (ref) => providers.find((provider) => provider.forge === ref.forge && provider.instance === ref.instance);
+	const route = (ref) => {
+		const provider = find(ref);
+		if (!provider) throw new UnknownForgeError(`No provider registered for ${ref.forge} on ${ref.instance}`, {
+			forge: ref.forge,
+			instance: ref.instance
+		});
+		return provider;
+	};
+	const parseUrl = (url) => {
+		for (const provider of providers) {
+			const parsed = provider.parseUrl(url);
+			if (parsed) return {
+				...parsed,
+				provider
+			};
+		}
+	};
+	return {
+		providers,
+		for: find,
+		forUrl: (url) => parseUrl(url)?.provider,
+		parseUrl,
+		repos: { get: (ref, options) => route(ref).repos.get(ref, options) },
+		threads: {
+			get: (ref, options) => route(ref).threads.get(ref, options),
+			async getMany(refs, options) {
+				const groups = /* @__PURE__ */ new Map();
+				const results = Array.from({ length: refs.length });
+				for (const [index, ref] of refs.entries()) {
+					const provider = find(ref);
+					if (!provider) {
+						const error = new UnknownForgeError(`No provider registered for ${ref.forge} on ${ref.instance}`, {
+							forge: ref.forge,
+							instance: ref.instance
+						});
+						results[index] = {
+							ok: false,
+							ref,
+							warning: toWarning("thread_unreadable", error, ref.number)
+						};
+						continue;
+					}
+					groups.set(provider, [...groups.get(provider) ?? [], index]);
+				}
+				await Promise.all([...groups].map(async ([provider, indexes]) => {
+					const batch = await provider.threads.getMany(indexes.map((index) => refs[index]), options);
+					for (const [position, index] of indexes.entries()) results[index] = batch[position];
+				}));
+				return results;
+			}
+		},
+		releases: {
+			list: (repo, options) => route(repo).releases.list(repo, options),
+			latest: (repo, options) => route(repo).releases.latest(repo, options)
+		},
+		securityAlerts: { list: (repo, options) => route(repo).securityAlerts.list(repo, options) },
+		search: {
+			threads: (query = {}) => mergeByTime(providers, "search.threads", query, (provider, page) => provider.search.threadsPage(page)),
+			repos: (query = {}) => mergeByTime(providers, "search.repos", query, (provider, page) => provider.search.reposPage(page))
+		},
+		get: (forge, instance) => providers.find((provider) => provider.forge === forge && (!instance || provider.instance === instance)),
+		all: (forge) => providers.filter((provider) => provider.forge === forge),
+		notifications: { list(options) {
+			const warnings = [];
+			return {
+				warnings,
+				async *[Symbol.asyncIterator]() {
+					for (const provider of providers) {
+						if (!provider.can("notifications.list")) continue;
+						const iterable = provider.notifications.list({
+							...options,
+							cursor: void 0
+						});
+						try {
+							yield* iterable;
+						} catch (error) {
+							warnings.push({
+								...toWarning("notifications_failed", error),
+								subject: `${provider.forge}:${provider.instance}`
+							});
+						} finally {
+							warnings.push(...iterable.warnings);
+						}
+					}
+				}
+			};
+		} }
+	};
+}
+//#endregion
+export { createForges as t };

package/dist/pushin/index.d.mts

@@ -0,0 +1,2 @@
+import { a as toActor, i as pushinScopesFor, n as PushinOptions, o as toComment, r as pushin, s as toRepo, t as PushinAuth } from "../index-DEt25E1w.mjs";
+export { PushinAuth, PushinOptions, pushin, pushinScopesFor, toActor as toPushinActor, toComment as toPushinComment, toRepo as toPushinRepo };

package/dist/pushin/index.mjs

@@ -0,0 +1 @@
+export { t as pushin, n as pushinScopesFor, r as toPushinActor, i as toPushinComment, a as toPushinRepo } from "../pushin-CkxgJ2cU.mjs";

package/dist/pushin-CkxgJ2cU.mjs

@@ -0,0 +1,343 @@
+import { A as toPage, C as requireIssueOrPull, O as toDate, T as resolveToken, f as getManyConcurrently, i as githubShapedWeb, l as createListing, n as perKind, r as verb, t as defineForgeProvider } from "./define-D3yEXtKK.mjs";
+//#region src/pushin/normalise.ts
+const FORGE = "pushin";
+function toActor(origin, user) {
+	if (!user) return;
+	return {
+		...origin,
+		login: user.login,
+		id: String(user.id ?? user.login),
+		name: user.name ?? void 0,
+		avatarUrl: user.avatar_url,
+		url: user.html_url,
+		typeRaw: user.type,
+		isBotHint: user.type === "Bot"
+	};
+}
+function toRepoRef(origin, raw) {
+	const [owner, name] = raw.full_name.split("/");
+	return {
+		...origin,
+		owner: raw.owner?.login ?? owner ?? "",
+		name: raw.name ?? name ?? "",
+		externalId: raw.node_id ?? String(raw.id)
+	};
+}
+function toRepo(origin, raw) {
+	const visibility = raw.visibility === "private" || raw.private ? "private" : "public";
+	return {
+		ref: toRepoRef(origin, raw),
+		description: raw.description ?? void 0,
+		defaultBranch: raw.default_branch,
+		visibility,
+		visibilityRaw: raw.visibility,
+		isFork: false,
+		isArchived: false,
+		topics: raw.topics ?? [],
+		url: raw.html_url,
+		cloneUrls: raw.clone_url ? { https: raw.clone_url } : void 0,
+		createdAt: toDate(raw.created_at),
+		updatedAt: toDate(raw.updated_at),
+		owner: toActor(origin, raw.owner),
+		homepage: raw.homepage || void 0,
+		stars: raw.stargazers_count,
+		forks: raw.forks_count,
+		permissions: toPermissions(raw.permissions),
+		raw
+	};
+}
+function toLabel(raw) {
+	return {
+		name: raw.name,
+		colour: raw.color && /^[0-9a-f]{6}$/i.test(raw.color) ? raw.color : void 0,
+		description: raw.description ?? void 0
+	};
+}
+function toPermissions(raw) {
+	return raw && {
+		admin: raw.admin ?? false,
+		maintain: raw.maintain ?? false,
+		push: raw.push ?? false,
+		triage: raw.triage ?? false,
+		pull: raw.pull ?? false
+	};
+}
+function toRole(raw) {
+	const permissions = raw.permissions ?? {};
+	if (permissions.admin) return "admin";
+	if (permissions.maintain) return "maintain";
+	if (permissions.push) return "write";
+	if (permissions.triage) return "triage";
+	return permissions.pull ? "read" : "none";
+}
+function toCollaborator(origin, raw) {
+	return {
+		actor: toActor(origin, raw),
+		role: toRole(raw),
+		roleRaw: raw.role_name,
+		permissions: toPermissions(raw.permissions),
+		raw
+	};
+}
+function toComment(thread, raw) {
+	return {
+		ref: {
+			forge: FORGE,
+			instance: thread.instance,
+			thread,
+			id: String(raw.id)
+		},
+		body: raw.body,
+		author: toActor({
+			forge: FORGE,
+			instance: thread.instance
+		}, raw.user),
+		createdAt: toDate(raw.created_at),
+		updatedAt: toDate(raw.updated_at),
+		raw
+	};
+}
+const REASONS = {
+	assign: "assigned",
+	review_requested: "review_requested",
+	mention: "mention",
+	author: "author",
+	comment: "comment",
+	subscribed: "subscribed",
+	state_change: "state_change",
+	manual: "manual"
+};
+function toNotification(origin, raw) {
+	const repo = toRepoRef(origin, raw.repository);
+	const kind = raw.subject.type === "Issue" ? "issue" : raw.subject.type === "PullRequest" ? "pull_request" : void 0;
+	const number = /\/(\d+)\/?$/.exec(raw.subject.url)?.[1];
+	return {
+		ref: {
+			...origin,
+			id: String(raw.id)
+		},
+		subject: kind && number ? {
+			type: "thread",
+			thread: {
+				...origin,
+				repo,
+				kind,
+				number
+			}
+		} : {
+			type: "other",
+			typeRaw: raw.subject.type,
+			repo,
+			url: raw.subject.url
+		},
+		subjectTypeRaw: raw.subject.type,
+		reason: REASONS[raw.reason] ?? "unknown",
+		reasonRaw: raw.reason,
+		unread: raw.unread,
+		title: raw.subject.title,
+		subjectState: "unknown",
+		updatedAt: toDate(raw.updated_at) ?? /* @__PURE__ */ new Date(0),
+		lastReadAt: toDate(raw.last_read_at),
+		url: raw.html_url ?? raw.subject.url,
+		raw
+	};
+}
+function toThread(ref, raw) {
+	const origin = {
+		forge: FORGE,
+		instance: ref.instance
+	};
+	const kind = raw.pull_request ? "pull_request" : ref.kind;
+	const merged = kind === "pull_request" && (raw.merged || raw.merged_at || raw.pull_request?.merged_at || raw.state === "merged");
+	const state = merged ? "merged" : raw.state === "closed" ? "closed" : "open";
+	return {
+		ref: {
+			...ref,
+			kind,
+			externalId: raw.node_id ?? String(raw.id)
+		},
+		kind,
+		title: raw.title,
+		body: raw.body ?? void 0,
+		state,
+		stateRaw: merged ? "merged" : raw.state,
+		isDraft: kind === "pull_request" && (raw.draft ?? false),
+		author: toActor(origin, raw.user),
+		assignees: (raw.assignees ?? []).flatMap((user) => toActor(origin, user) ?? []),
+		reviewers: [],
+		labels: (raw.labels ?? []).map(toLabel),
+		url: raw.html_url,
+		createdAt: toDate(raw.created_at),
+		updatedAt: toDate(raw.updated_at),
+		closedAt: toDate(raw.closed_at),
+		lastActivityAt: toDate(raw.updated_at),
+		locked: raw.locked,
+		commentCount: raw.comments,
+		branches: kind === "pull_request" && (raw.head || raw.base) ? {
+			head: {
+				ref: raw.head?.ref ?? "",
+				sha: raw.head?.sha ?? void 0
+			},
+			base: { ref: raw.base?.ref ?? "" }
+		} : void 0,
+		raw
+	};
+}
+//#endregion
+//#region src/pushin/index.ts
+function setupPushin({ options, instance, origin: context, fetcher, baseUrl }) {
+	const anonymous = options.auth?.type === "anonymous";
+	const list = createListing(fetcher, "per_page");
+	const repoPath = (repo) => `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.name)}`;
+	function threadPath(ref) {
+		return `${repoPath(ref.repo)}/${ref.kind === "pull_request" ? "pulls" : "issues"}/${encodeURIComponent(ref.number)}`;
+	}
+	async function get(thread, options) {
+		const ref = requireIssueOrPull(thread, context, "read");
+		const { data } = await fetcher.json(threadPath(ref), { signal: options?.signal });
+		return toThread(ref, data);
+	}
+	async function listPage(repo, query = {}) {
+		if (query.kind && query.kind !== "issue" && query.kind !== "pull_request") return {
+			items: [],
+			warnings: [{
+				code: "kind_unsupported",
+				message: `Pushin.eu has no listing for ${query.kind}s`
+			}]
+		};
+		const kind = query.kind === "pull_request" ? "pull_request" : "issue";
+		const result = await fetcher.page(`${repoPath(repo)}/${kind === "pull_request" ? "pulls" : "issues"}`, {
+			query: {
+				state: query.state === "merged" ? "closed" : query.state,
+				per_page: query.perPage
+			},
+			cursor: query.cursor,
+			signal: query.signal
+		});
+		return toPage(result, (raw) => {
+			const thread = toThread({
+				forge: FORGE,
+				instance,
+				repo,
+				kind,
+				number: String(raw.number)
+			}, raw);
+			return query.kind === "issue" && raw.pull_request || query.state === "merged" && thread.state !== "merged" ? void 0 : thread;
+		});
+	}
+	async function commentsPage(thread, listOptions = {}) {
+		const ref = requireIssueOrPull(thread, context, "read comments on");
+		const result = await fetcher.page(`${threadPath(ref)}/comments`, {
+			query: { per_page: listOptions.perPage },
+			cursor: listOptions.cursor,
+			signal: listOptions.signal
+		});
+		return toPage(result, (raw) => toComment(ref, raw));
+	}
+	async function eventsPage(thread, listOptions = {}) {
+		const ref = requireIssueOrPull(thread, context, "read events for");
+		const page = await commentsPage(ref, listOptions);
+		return {
+			...page,
+			items: page.items.map((comment) => ({
+				forge: FORGE,
+				instance,
+				id: comment.ref.id,
+				kind: "comment",
+				kindRaw: "comment",
+				summary: `${comment.author?.login ?? "someone"} commented`,
+				occurredAt: comment.createdAt ?? /* @__PURE__ */ new Date(0),
+				actor: comment.author,
+				repo: ref.repo,
+				thread: ref,
+				source: "poll",
+				detail: {
+					type: "comment",
+					comment: comment.ref,
+					body: comment.body
+				},
+				payload: comment.raw
+			}))
+		};
+	}
+	return {
+		traits: {
+			eventKinds: "native",
+			authKinds: ["token", "anonymous"]
+		},
+		users: { me: verb(true, async (options) => {
+			const { data } = await fetcher.json("/user", { signal: options?.signal });
+			return {
+				...toActor({
+					forge: FORGE,
+					instance
+				}, data),
+				company: data.company ?? void 0,
+				raw: data
+			};
+		}) },
+		repos: {
+			get: verb(true, async (repo, options) => toRepo({
+				forge: FORGE,
+				instance
+			}, (await fetcher.json(repoPath(repo), { signal: options?.signal })).data)),
+			listPage: verb(true, (listOptions = {}) => list("/user/repos", listOptions, (raw) => toRepo({
+				forge: FORGE,
+				instance
+			}, raw))),
+			labelsPage: verb(true, (repo, listOptions = {}) => list(`${repoPath(repo)}/labels`, listOptions, (raw) => toLabel(raw))),
+			collaboratorsPage: verb(!anonymous, (repo, listOptions = {}) => list(`${repoPath(repo)}/collaborators`, listOptions, (raw) => toCollaborator({
+				forge: FORGE,
+				instance
+			}, raw)))
+		},
+		threads: {
+			get: perKind({
+				issue: true,
+				pull_request: true
+			}, get),
+			listPage: perKind({
+				issue: true,
+				pull_request: true
+			}, listPage),
+			getMany: verb(true, (refs, options) => getManyConcurrently(refs, get, options)),
+			eventsPage: verb("emulated", eventsPage),
+			commentsPage: perKind({
+				issue: true,
+				pull_request: true
+			}, commentsPage)
+		},
+		notifications: { listPage: verb(true, (listOptions = {}) => list("/notifications", listOptions, (raw) => toNotification({
+			forge: FORGE,
+			instance
+		}, raw), { query: {
+			all: listOptions.all,
+			since: listOptions.since?.toISOString()
+		} })) },
+		web: githubShapedWeb(baseUrl.replace(/\/api\/v1$/, ""), {
+			pull: "pulls",
+			commentFragment: "comment-",
+			file: (at) => `/blob/${encodeURIComponent(at)}`,
+			lineFragment: (line) => `L${line}`
+		}),
+		webhooks: {},
+		scopes: pushinScopesFor
+	};
+}
+/** Creates a Pushin.eu provider. */
+const pushin = /* @__PURE__ */ defineForgeProvider({
+	forge: FORGE,
+	experimental: true,
+	anonymous: true,
+	baseUrl: "https://pushin.eu",
+	apiPath: "/api/v1",
+	headers: { accept: "application/vnd.github+json" },
+	authHeaders: ({ options: { auth } }) => auth?.type === "token" ? async () => ({ authorization: `Bearer ${await resolveToken(auth)}` }) : void 0,
+	setup: setupPushin
+});
+/** Scope requirements for a Pushin.eu operation. */
+function pushinScopesFor(_verb) {
+	return { note: "A personal access token created in Settings; Pushin.eu does not scope tokens per resource" };
+}
+//#endregion
+export { toRepo as a, toComment as i, pushinScopesFor as n, toActor as r, pushin as t };

package/dist/schema/Actor.json

@@ -0,0 +1,96 @@
+{
+  "$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`."
+    },
+    "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",
+  "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"
+    }
+  }
+}

package/dist/schema/AlertSupport.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "dependency": {
+      "$ref": "#/definitions/Support"
+    },
+    "code_scanning": {
+      "$ref": "#/definitions/Support"
+    },
+    "secret": {
+      "$ref": "#/definitions/Support"
+    },
+    "advisory": {
+      "$ref": "#/definitions/Support"
+    }
+  },
+  "required": [
+    "dependency",
+    "code_scanning",
+    "secret",
+    "advisory"
+  ],
+  "description": "Support per security alert kind.",
+  "x-forges-type": "AlertSupport",
+  "definitions": {
+    "Support": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "const": "emulated"
+        },
+        {
+          "type": "string",
+          "const": "experimental"
+        },
+        {
+          "type": "string",
+          "const": "unverified"
+        }
+      ],
+      "description": "Capability flag. Every value other than `false` means the operation is available:\n\n- `true`: native, and verified against the forge's responses.\n- `'experimental'`: native and verified, but built on an API the forge marks unstable, so it can change.\n- `'emulated'`: composed from other calls, so the result is approximate.\n- `'unverified'`: implemented, but not yet verified against the forge's responses, so it may not work.",
+      "x-forges-type": "Support"
+    }
+  }
+}

package/dist/schema/AuthKind.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "enum": [
+    "token",
+    "basic",
+    "app",
+    "app_password",
+    "oauth",
+    "anonymous"
+  ],
+  "description": "The credential types that a provider can accept.",
+  "x-forges-type": "AuthKind",
+  "definitions": {}
+}