@deepseek-ai/dsh-experimental-forge 0.0.0-stage → 0.2.2-alpha.3

package/lib/index.js

@@ -0,0 +1,537 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { MAX_TIMER_DELAY_MS, deadline } from "@deepseek-ai/dsh-timeout";
+import { brandString } from "@deepseek-ai/dsh-brand";
+//#region lib/types/keys.js
+/** Canonical identities for change requests. */
+/**
+* Build the canonical identity of a change request. Host, owner, and name
+* compare case-insensitively, as they do on the hosts this vocabulary serves.
+* @param ref - change request to identify.
+* @returns `<forge>:<host>/<owner>/<name>#<number>` in lowercase.
+*/
+function changeRequestKey(ref) {
+	const { forge, host, owner, name } = ref.repository;
+	return brandString(`${forge}:${host}/${owner}/${name}#${ref.number}`.toLowerCase());
+}
+//#endregion
+//#region lib/types/schedule.js
+/** Poll cadence for watched change requests. */
+/**
+* Choose the delay before the next poll of one change request. Failures back
+* off exponentially from the active interval; merged change requests stop
+* polling, while closed ones use the idle cadence to detect reopening.
+* @param result - latest snapshot or failure.
+* @param failures - consecutive failures, counting `result` when it is one.
+* @param intervals - configured cadence.
+* @returns the delay in milliseconds, or undefined after a terminal state.
+*/
+function nextPollDelay(result, failures, intervals) {
+	if ("code" in result) return Math.min(intervals.maxBackoffMs, intervals.activeIntervalMs * 2 ** failures);
+	if (result.state === "merged") return void 0;
+	if (result.state === "closed") return intervals.idleIntervalMs;
+	return result.checksRollup === "pending" || result.mergeability === "unknown" ? intervals.activeIntervalMs : intervals.idleIntervalMs;
+}
+//#endregion
+//#region lib/types/index.js
+/** Registry of code-host providers with provider-neutral change requests and shared status polling. */
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+* Registry of forge providers. Watchers of one change request share a single
+* polling loop; each forge has at most one fetch in flight, which batches
+* every due change request of that forge.
+*/
+var ForgeService = class extends Service {
+	static Config = z.object({
+		activeIntervalMs: z.number().default(3e4),
+		idleIntervalMs: z.number().default(12e4),
+		maxBackoffMs: z.number().default(6e5),
+		fetchTimeoutMs: z.number().default(3e4)
+	});
+	config;
+	providers = /* @__PURE__ */ new Map();
+	watches = /* @__PURE__ */ new Map();
+	fetching = /* @__PURE__ */ new Set();
+	pending = /* @__PURE__ */ new Set();
+	lifetime = new AbortController();
+	timer;
+	/**
+	* Poll what is due. A field rather than a method, so the timer runs it on
+	* the instance itself: a polling round started through a caller's `ctx.forge`
+	* would otherwise run on that caller's shadow receiver, and every later round
+	* would nest one more shadow until a property write overflows the stack.
+	*/
+	tick = () => {
+		this.timer = void 0;
+		this.poll();
+	};
+	constructor(ctx, config) {
+		super(ctx, "forge");
+		this.config = config;
+		for (const key of [
+			"activeIntervalMs",
+			"idleIntervalMs",
+			"maxBackoffMs",
+			"fetchTimeoutMs"
+		]) {
+			const value = this.config[key];
+			if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) throw new Error(`forge: ${key} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+		}
+		if (this.config.maxBackoffMs < this.config.activeIntervalMs) throw new Error("forge: maxBackoffMs must be greater than or equal to activeIntervalMs");
+		ctx.effect(() => async () => {
+			this.lifetime.abort(/* @__PURE__ */ new Error("forge service disposed"));
+			clearTimeout(this.timer);
+			this.timer = void 0;
+			await Promise.allSettled(this.pending);
+		}, "forge: stop polling");
+	}
+	/**
+	* Register the provider of one forge family as an effect on the calling
+	* fiber. Watches of that forge receive an `unavailable` failure when the
+	* registration ends. Unregistering cancels and awaits its in-flight calls;
+	* results from the withdrawn registration are discarded.
+	* @param provider - provider to serve `provider.forge`.
+	* @returns the disposer that unregisters the provider and waits for its calls to finish.
+	* @throws when another provider already serves the same forge.
+	*/
+	register(provider) {
+		const dispose = this.ctx.effect(() => {
+			if (this.providers.has(provider.forge)) throw new Error(`forge: a provider for "${provider.forge}" is already registered`);
+			const registration = {
+				provider,
+				lifetime: new AbortController(),
+				pending: /* @__PURE__ */ new Set()
+			};
+			this.providers.set(provider.forge, registration);
+			for (const watch of this.watches.values()) if (watch.ref.repository.forge === provider.forge) watch.dueAt = Date.now();
+			this.providersChanged(provider.forge);
+			this.schedule();
+			return async () => {
+				this.providers.delete(provider.forge);
+				registration.lifetime.abort(/* @__PURE__ */ new Error(`forge: provider "${provider.forge}" was unregistered`));
+				for (const watch of [...this.watches.values()]) if (watch.ref.repository.forge === provider.forge) this.settle(watch, this.missing(provider.forge), void 0);
+				this.providersChanged(provider.forge);
+				this.schedule();
+				await Promise.allSettled(registration.pending);
+			};
+		}, `forge.register(${provider.forge})`);
+		return async () => {
+			await dispose();
+		};
+	}
+	/**
+	* Map a Git remote URL to a repository through the first provider that serves it.
+	* @param url - fetch or push URL as Git reports it.
+	* @returns the repository, or undefined when no provider serves the URL.
+	*/
+	repositoryFromRemote(url) {
+		for (const { provider } of this.providers.values()) {
+			const repository = provider.repositoryFromRemote(url);
+			if (repository !== void 0) return repository;
+		}
+	}
+	/**
+	* Map a change request web URL through the first provider that serves it.
+	* @param url - web URL of a pull or merge request.
+	* @returns the change request, or undefined when no provider serves the URL.
+	*/
+	changeRequestFromUrl(url) {
+		for (const { provider } of this.providers.values()) {
+			const ref = provider.changeRequestFromUrl(url);
+			if (ref !== void 0) return ref;
+		}
+	}
+	/**
+	* Build the canonical web URL of a change request.
+	* @param ref - change request served by a registered provider.
+	* @returns the provider's canonical URL.
+	* @throws when no provider serves the change request's forge.
+	*/
+	changeRequestUrl(ref) {
+		return this.provider(ref.repository.forge).changeRequestUrl(ref);
+	}
+	/**
+	* Find open change requests whose head is `branch`, excluding the default branch and forks.
+	* @param repository - repository served by a registered provider.
+	* @param branch - head branch name on the host.
+	* @param signal - cancellation for the lookup.
+	* @returns matching change requests, newest first as the provider reports them.
+	* @throws when no provider serves the repository's forge or the lookup fails.
+	*/
+	async findByHead(repository, branch, signal) {
+		return await this.invoke(this.registration(repository.forge), signal, (provider, operation) => provider.findByHead(repository, branch, operation));
+	}
+	/**
+	* Report whether the provider can reach the repository's host with current credentials.
+	* @param repository - repository served by a registered provider.
+	* @param signal - cancellation for the probe.
+	* @returns the provider's readiness for the host.
+	* @throws when no provider serves the repository's forge.
+	*/
+	async readiness(repository, signal) {
+		return await this.invoke(this.registration(repository.forge), signal, (provider, operation) => provider.readiness(repository.host, operation));
+	}
+	/**
+	* Mark a draft change request ready for review, then poll it at once when it is watched.
+	* @param ref - change request served by a registered provider.
+	* @param signal - cancellation of the request.
+	* @returns undefined once the host accepted the change, or why it did not.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async markReady(ref, signal) {
+		const failure = await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.markReady(ref, operation));
+		this.refresh(ref);
+		return failure;
+	}
+	/**
+	* Merge a change request while its head is still `request.headSha`, then
+	* poll it at once when it is watched.
+	* @param ref - change request served by a registered provider.
+	* @param request - merge method and the head commit the user confirmed.
+	* @param signal - cancellation of the request.
+	* @returns undefined once the host merged it, or why it did not.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async merge(ref, request, signal) {
+		const failure = await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.merge(ref, request, operation));
+		this.refresh(ref);
+		return failure;
+	}
+	/**
+	* Read complete check details independently of periodic polling.
+	* @param ref - change request served by a registered provider.
+	* @param signal - cancellation of the detail view.
+	* @returns a complete snapshot or the provider's failure; unsupported providers return unavailable.
+	* @throws on cancellation, provider disposal, or expiry of this read's own `fetchTimeoutMs` deadline.
+	*/
+	async fetchChecks(ref, signal) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const timeout = __addDisposableResource(env_1, deadline(signal, this.config.fetchTimeoutMs, "FORGE_FETCH_TIMEOUT"), false);
+			return await this.invoke(this.registration(ref.repository.forge), timeout.signal, (provider, operation) => provider.fetchChecks?.(ref, operation) ?? Promise.resolve({
+				code: "unavailable",
+				message: "This provider does not support complete check reads"
+			}));
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	}
+	/**
+	* Read the changes of a change request as its host computes them.
+	* @param ref - change request served by a registered provider.
+	* @param signal - cancellation of the read.
+	* @returns one unified patch with `a/` and `b/` path prefixes, or why the host did not provide it.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async diff(ref, signal) {
+		return await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.diff(ref, operation));
+	}
+	/**
+	* Publish one comment or a completed review, then refresh the watched status.
+	* @param ref - change request served by a registered provider.
+	* @param request - explicitly selected commit, comments, and review decision.
+	* @param signal - request cancellation.
+	* @returns a publication URL or a failure, including an unknown write outcome.
+	*/
+	async submitReview(ref, request, signal) {
+		const result = await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.submitReview?.(ref, request, operation) ?? Promise.resolve({
+			ok: false,
+			code: "unsupported",
+			message: "This provider does not support review submission"
+		}));
+		this.refresh(ref);
+		return result;
+	}
+	/**
+	* Read the text of one file at a commit of a change request's repository.
+	* @param ref - change request served by a registered provider.
+	* @param commit - commit object name.
+	* @param path - path relative to the repository root.
+	* @param signal - cancellation of the read.
+	* @returns the text, or why the host did not provide it.
+	* @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
+	*/
+	async fileText(ref, commit, path, signal) {
+		return await this.invoke(this.registration(ref.repository.forge), signal, (provider, operation) => provider.fileText(ref, commit, path, operation));
+	}
+	/**
+	* Build the web page of one file at a commit of a change request's repository.
+	* @param ref - change request served by a registered provider.
+	* @param commit - commit object name.
+	* @param path - path relative to the repository root.
+	* @returns the provider's URL.
+	* @throws when no provider serves the change request's forge.
+	*/
+	fileUrl(ref, commit, path) {
+		return this.provider(ref.repository.forge).fileUrl(ref, commit, path);
+	}
+	/**
+	* Watch one change request as an effect on the calling fiber. The first
+	* watcher starts polling at once; listeners receive every later result,
+	* and `latest` returns the current one. Polling stops when the last watcher
+	* leaves. Listeners must not throw; a thrown error is logged and skipped.
+	* @param ref - change request to poll.
+	* @param listener - receives each polling result.
+	* @returns the disposer that stops this watch.
+	*/
+	watch(ref, listener) {
+		const key = changeRequestKey(ref);
+		const dispose = this.ctx.effect(() => {
+			let watch = this.watches.get(key);
+			if (watch === void 0) {
+				watch = {
+					key,
+					ref,
+					listeners: /* @__PURE__ */ new Set(),
+					latest: void 0,
+					dueAt: Date.now(),
+					failures: 0
+				};
+				this.watches.set(key, watch);
+				this.schedule();
+			}
+			const owned = watch;
+			owned.listeners.add(listener);
+			return () => {
+				owned.listeners.delete(listener);
+				if (owned.listeners.size === 0 && this.watches.get(key) === owned) {
+					this.watches.delete(key);
+					this.schedule();
+				}
+			};
+		}, "forge.watch()");
+		return () => void dispose();
+	}
+	/**
+	* Poll a watched change request at once, including after a terminal state.
+	* A fetch already in flight is followed immediately by another fetch; an
+	* unwatched change request is unchanged.
+	* @param ref - change request to poll.
+	*/
+	refresh(ref) {
+		const watch = this.watches.get(changeRequestKey(ref));
+		if (watch === void 0) return;
+		watch.dueAt = Date.now();
+		this.schedule();
+	}
+	/**
+	* Read the latest polling result of a watched change request.
+	* @param ref - change request to read.
+	* @returns the latest result, or undefined before the first result or without a watch.
+	*/
+	latest(ref) {
+		return this.watches.get(changeRequestKey(ref))?.latest;
+	}
+	provider(forge) {
+		return this.registration(forge).provider;
+	}
+	providersChanged(forge) {
+		if (this.lifetime.signal.aborted) return;
+		const task = this.ctx.parallel("forge/providers-changed", forge).catch((error) => {
+			this.ctx.logger.warn(`forge: provider change listener failed: ${String(error)}`);
+		});
+		this.pending.add(task);
+		task.then(() => this.pending.delete(task));
+	}
+	registration(forge) {
+		const registration = this.providers.get(forge);
+		if (registration === void 0) throw new Error(`forge: ${this.missing(forge).message}`);
+		return registration;
+	}
+	async invoke(registration, signal, action) {
+		const operation = AbortSignal.any([
+			signal,
+			this.lifetime.signal,
+			registration.lifetime.signal
+		]);
+		operation.throwIfAborted();
+		const completion = Promise.withResolvers();
+		registration.pending.add(completion.promise);
+		this.pending.add(completion.promise);
+		try {
+			const result = await action(registration.provider, operation);
+			operation.throwIfAborted();
+			return result;
+		} finally {
+			registration.pending.delete(completion.promise);
+			this.pending.delete(completion.promise);
+			completion.resolve();
+		}
+	}
+	missing(forge) {
+		return {
+			code: "unavailable",
+			message: `no provider is registered for "${forge}"`
+		};
+	}
+	schedule() {
+		clearTimeout(this.timer);
+		this.timer = void 0;
+		if (this.lifetime.signal.aborted) return;
+		let next;
+		for (const watch of this.watches.values()) {
+			if (watch.dueAt === void 0 || this.fetching.has(watch.ref.repository.forge)) continue;
+			next = next === void 0 ? watch.dueAt : Math.min(next, watch.dueAt);
+		}
+		if (next === void 0) return;
+		this.timer = setTimeout(this.tick, Math.max(0, next - Date.now()));
+	}
+	poll() {
+		const now = Date.now();
+		const due = /* @__PURE__ */ new Map();
+		for (const watch of this.watches.values()) {
+			const forge = watch.ref.repository.forge;
+			if (watch.dueAt === void 0 || watch.dueAt > now || this.fetching.has(forge)) continue;
+			const batch = due.get(forge);
+			if (batch === void 0) due.set(forge, [watch]);
+			else batch.push(watch);
+		}
+		for (const [forge, batch] of due) {
+			const task = this.fetch(forge, batch);
+			this.pending.add(task);
+			task.then(() => this.pending.delete(task));
+		}
+		this.schedule();
+	}
+	/** Fetch one forge's batch; never rejects. */
+	async fetch(forge, batch) {
+		this.fetching.add(forge);
+		for (const watch of batch) watch.dueAt = void 0;
+		let results;
+		let failure;
+		const registration = this.providers.get(forge);
+		try {
+			if (registration === void 0) failure = this.missing(forge);
+			else {
+				const env_2 = {
+					stack: [],
+					error: void 0,
+					hasError: false
+				};
+				try {
+					const timeout = __addDisposableResource(env_2, deadline(this.lifetime.signal, this.config.fetchTimeoutMs, "FORGE_FETCH_TIMEOUT"), false);
+					results = await this.invoke(registration, timeout.signal, (provider, operation) => provider.fetch(batch.map((watch) => watch.ref), operation));
+				} catch (e_2) {
+					env_2.error = e_2;
+					env_2.hasError = true;
+				} finally {
+					__disposeResources(env_2);
+				}
+			}
+		} catch (error) {
+			failure = {
+				code: "unavailable",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		} finally {
+			this.fetching.delete(forge);
+		}
+		if (this.lifetime.signal.aborted) return;
+		if (registration !== this.providers.get(forge)) {
+			this.schedule();
+			return;
+		}
+		for (const watch of batch) {
+			if (this.watches.get(watch.key) !== watch) continue;
+			const result = failure ?? results?.get(watch.key) ?? {
+				code: "unavailable",
+				message: `provider returned no result for ${watch.key}`
+			};
+			this.settle(watch, result, watch.dueAt);
+		}
+		this.schedule();
+	}
+	settle(watch, result, refreshAt) {
+		const fetchedAt = Date.now();
+		let update;
+		if ("code" in result) {
+			watch.failures++;
+			update = {
+				key: watch.key,
+				fetchedAt,
+				failure: result
+			};
+		} else {
+			watch.failures = 0;
+			update = {
+				key: watch.key,
+				fetchedAt,
+				snapshot: result
+			};
+		}
+		watch.latest = update;
+		const delay = nextPollDelay(result, watch.failures, this.config);
+		watch.dueAt = refreshAt ?? (delay === void 0 ? void 0 : fetchedAt + delay);
+		for (const listener of [...watch.listeners]) try {
+			listener(update);
+		} catch (error) {
+			this.ctx.logger.warn(`forge: change request listener failed: ${String(error)}`);
+		}
+	}
+};
+//#endregion
+export { ForgeService, ForgeService as default, changeRequestKey };