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

package/README.i18n.yaml

@@ -15,8 +15,8 @@
   en: d152484eb41ac6b4
   zh: 2f8a621b991260a1
 /deepseek-ai-dsh-experimental-forge/use-this-package:
-  en: 5f4f14ee9aad5072
-  zh: 6c8606796df24a3e
+  en: 9ca86ee541048ff2
+  zh: 7aef4feb76542dd6
 /deepseek-ai-dsh-experimental-forge/understand-the-implementation:
   en: e193cb547c47069b
   zh: faa517522402ea41

package/README.md

@@ -38,10 +38,14 @@ Mount the registry with at least one provider package, such as the GitHub provid
 
 `diff(ref, signal)` reads the change request's unified patch as the host computes it, with `a/` and `b/` path prefixes, and `fileText(ref, commit, path, signal)` reads one file of its repository at a commit. Both delegate to the provider of the reference's forge, throw when none is registered, and resolve to the text or to a `ForgeFailure`, which is `too-large` when the host or the provider refuses an answer over its size limit. `fileUrl(ref, commit, path)` returns the web page of that file at that commit.
 
-`ctx.forge.watch(ref, listener)` is also an effect. The first watcher of a change request polls it at once; `latest(ref)` returns the most recent result. Each forge has at most one fetch in flight, and that fetch includes every due change request of the forge. An open change request is polled every `activeIntervalMs` while checks are pending or mergeability is unknown, and every `idleIntervalMs` otherwise. Closed change requests use `idleIntervalMs` to detect reopening; merged requests stop automatic polling. `refresh(ref)` polls a watched change request at once, including after a terminal state; if a fetch is already in flight for its forge, another fetch starts immediately after it settles. A failed read repeats after `activeIntervalMs` doubled for each consecutive failure, up to `maxBackoffMs`, which must be at least `activeIntervalMs`. Unregistering a provider settles its watched change requests as `unavailable`. Polling stops when the last watcher leaves. The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge) lists the defaults.
+`fetchChecks(ref, signal)` reads one change request’s complete checks on demand. It has its own `fetchTimeoutMs` deadline and does not occupy the polling batch or publish to its watchers. Failure leaves previously polled snapshots intact. A provider without `fetchChecks` returns `unavailable`. Caller cancellation and provider or service disposal abort the read; disposal waits for it to settle.
+
+`ctx.forge.watch(ref, listener)` is also an effect. The first watcher of a change request polls it at once; `latest(ref)` returns the most recent result. Each forge has at most one polling fetch in flight, and that fetch includes every due change request of the forge. An open change request is polled every `activeIntervalMs` while checks are pending or mergeability is unknown, and every `idleIntervalMs` otherwise. Closed change requests use `idleIntervalMs` to detect reopening; merged requests stop automatic polling. `refresh(ref)` polls a watched change request at once, including after a terminal state; if a fetch is already in flight for its forge, another fetch starts immediately after it settles. A failed read repeats after `activeIntervalMs` doubled for each consecutive failure, up to `maxBackoffMs`, which must be at least `activeIntervalMs`. Unregistering a provider settles its watched change requests as `unavailable`. Polling stops when the last watcher leaves. The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-forge) lists the defaults.
 
 Reaching `fetchTimeoutMs` aborts the fetch signal with `FORGE_FETCH_TIMEOUT`. Providers must stop their work and settle when the signal aborts; rejected fetches become `unavailable` failures. A provider that ignores cancellation can stall polling and service disposal.
 
+Providers may implement `submitReview` to publish a line comment or a completed review at an explicit head commit. The registry returns unsupported when that capability is absent and refreshes watched status after a submission. Successful writes return their web URL; failures distinguish changed heads, refusals, and unknown outcomes. Callers must reconcile unknown outcomes before another submission. Pending drafts belong to the consumer, not the polling registry.
+
 -----
 
 <a id="understand-the-implementation"></a>

package/README.zh.md

@@ -38,10 +38,14 @@ kind: "package-reference"
 
 `diff(ref, signal)` 读取托管平台计算出的变更请求统一补丁，路径带 `a/` 与 `b/` 前缀；`fileText(ref, commit, path, signal)` 读取其仓库中某个提交下的一个文件。两者都委托给引用所属 forge 的提供方，没有注册提供方时抛错，resolve 为文本或 `ForgeFailure`；托管平台或提供方因结果超过其大小上限而拒绝时，失败为 `too-large`。`fileUrl(ref, commit, path)` 返回该文件在该提交下的网页地址。
 
-`ctx.forge.watch(ref, listener)` 同样是 effect。变更请求的第一个监听方会立即触发轮询；`latest(ref)` 返回最近一次结果。每个 forge 同时最多只有一次读取在进行，这次读取包含该 forge 所有到期的变更请求。打开状态的变更请求在检查未完成或可合并性未知时每 `activeIntervalMs` 轮询一次，否则每 `idleIntervalMs` 轮询一次。已关闭的变更请求按 `idleIntervalMs` 轮询以检测重新打开；已合并的停止自动轮询。`refresh(ref)` 立即轮询一个被监听的变更请求，已结束的也包括在内；该 forge 已有读取在进行时，等待其结束后立即再读一次。读取失败后，重试间隔为 `activeIntervalMs` 按连续失败次数翻倍，最长 `maxBackoffMs`；该值必须大于或等于 `activeIntervalMs`。注销提供方会让其被监听的变更请求以 `unavailable` 结束。最后一个监听方离开后轮询停止。默认值见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge)。
+`fetchChecks(ref, signal)` 按需读取单个变更请求的完整检查，使用独立的 `fetchTimeoutMs` 时限，不占用轮询批次，也不向其监听方发布结果。读取失败时保留已有轮询快照。提供方未实现 `fetchChecks` 时返回 `unavailable`。调用方取消、提供方或服务销毁都会中止读取；销毁会等待读取结束。
+
+`ctx.forge.watch(ref, listener)` 同样是 effect。变更请求的第一个监听方会立即触发轮询；`latest(ref)` 返回最近一次结果。每个 forge 同时最多只有一次轮询读取在进行，这次读取包含该 forge 所有到期的变更请求。打开状态的变更请求在检查未完成或可合并性未知时每 `activeIntervalMs` 轮询一次，否则每 `idleIntervalMs` 轮询一次。已关闭的变更请求按 `idleIntervalMs` 轮询以检测重新打开；已合并的停止自动轮询。`refresh(ref)` 立即轮询一个被监听的变更请求，已结束的也包括在内；该 forge 已有读取在进行时，等待其结束后立即再读一次。读取失败后，重试间隔为 `activeIntervalMs` 按连续失败次数翻倍，最长 `maxBackoffMs`；该值必须大于或等于 `activeIntervalMs`。注销提供方会让其被监听的变更请求以 `unavailable` 结束。最后一个监听方离开后轮询停止。默认值见[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-forge)。
 
 达到 `fetchTimeoutMs` 时，读取信号会以 `FORGE_FETCH_TIMEOUT` 中止。提供方必须在信号中止时停止工作并结束请求；被拒绝的读取会转为 `unavailable` 失败。忽略取消的提供方可能阻塞轮询和服务销毁。
 
+provider 可以实现 `submitReview`，在指定的 head 提交上发布行内评论或完整评审。未实现该能力时，注册表返回不支持；提交结束后会刷新受关注的状态。成功的写操作返回网页 URL；失败区分 head 变化、明确拒绝与结果不明。调用方必须先核对结果不明的操作，再次提交。待提交草稿由消费者管理，不由轮询注册表保存。
+
 -----
 
 <a id="understand-the-implementation"></a>

package/lib/index.js

@@ -255,6 +255,32 @@ var ForgeService = class extends Service {
 		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.
@@ -265,6 +291,22 @@ var ForgeService = class extends Service {
 		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.
@@ -425,19 +467,19 @@ var ForgeService = class extends Service {
 		try {
 			if (registration === void 0) failure = this.missing(forge);
 			else {
-				const env_1 = {
+				const env_2 = {
 					stack: [],
 					error: void 0,
 					hasError: false
 				};
 				try {
-					const timeout = __addDisposableResource(env_1, deadline(this.lifetime.signal, this.config.fetchTimeoutMs, "FORGE_FETCH_TIMEOUT"), false);
+					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_1) {
-					env_1.error = e_1;
-					env_1.hasError = true;
+				} catch (e_2) {
+					env_2.error = e_2;
+					env_2.hasError = true;
 				} finally {
-					__disposeResources(env_1);
+					__disposeResources(env_2);
 				}
 			}
 		} catch (error) {

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 /** Registry of code-host providers with provider-neutral change requests and shared status polling. */
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import type { ChangeRequestListener, ChangeRequestRef, ChangeRequestUpdate, Config, ForgeActionFailure, ForgeFailure, ForgeProvider, ForgeReadiness, ForgeRepository, MergeRequest } from './types.ts';
+import type { ChangeRequestListener, ChangeRequestRef, ChangeRequestSnapshot, ChangeRequestUpdate, Config, ForgeActionFailure, ForgeFailure, ForgeProvider, ForgeReadiness, ForgeRepository, ForgeReviewRequest, ForgeReviewResult, MergeRequest } from './types.ts';
 export { changeRequestKey } from './keys.ts';
 export type * from './types.ts';
 declare module '@deepseek-ai/cordis' {
@@ -104,6 +104,14 @@ export declare class ForgeService extends Service {
      * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
      */
     merge(ref: ChangeRequestRef, request: MergeRequest, signal: AbortSignal): Promise<ForgeActionFailure | undefined>;
+    /**
+     * 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.
+     */
+    fetchChecks(ref: ChangeRequestRef, signal: AbortSignal): Promise<ChangeRequestSnapshot | ForgeFailure>;
     /**
      * Read the changes of a change request as its host computes them.
      * @param ref - change request served by a registered provider.
@@ -112,6 +120,14 @@ export declare class ForgeService extends Service {
      * @throws when no provider serves the change request's forge, or with `signal.reason` when it aborts.
      */
     diff(ref: ChangeRequestRef, signal: AbortSignal): Promise<string | ForgeFailure>;
+    /**
+     * 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.
+     */
+    submitReview(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise<ForgeReviewResult>;
     /**
      * Read the text of one file at a commit of a change request's repository.
      * @param ref - change request served by a registered provider.

package/lib/types/types.d.ts

@@ -126,6 +126,36 @@ export interface MergeRequest {
     /** Commit object name the head must still have; the merge is refused once the head moves. */
     readonly headSha: string;
 }
+/** One inline comment addressed to the old or new side of a pull request diff. */
+export interface ForgeLineComment {
+    readonly path: string;
+    readonly side: 'L' | 'R';
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly body: string;
+}
+/** A single published comment or one completed review containing all pending comments. */
+export type ForgeReviewRequest = {
+    /** Commit the user reviewed; providers must check it before writing and address that commit explicitly. */
+    readonly headSha: string;
+} & ({
+    readonly kind: 'comment';
+    readonly comment: ForgeLineComment;
+} | {
+    readonly kind: 'review';
+    readonly event: 'comment' | 'approve' | 'request-changes';
+    readonly body: string;
+    readonly comments: readonly ForgeLineComment[];
+});
+/** Result of a review write; unknown outcomes must be checked on the host before another submission. */
+export type ForgeReviewResult = {
+    readonly ok: true;
+    readonly url: string;
+} | {
+    readonly ok: false;
+    readonly code: 'unsupported' | 'stale' | 'failed' | 'unknown';
+    readonly message: string;
+};
 /** Why a provider could not change a change request. */
 export interface ForgeActionFailure {
     /**
@@ -150,6 +180,8 @@ export interface ForgeReadiness {
 export interface ForgeProvider {
     /** Forge family name stored in every repository this provider returns. */
     readonly forge: string;
+    /** Publish a comment or completed review. Omission declares that this provider cannot write reviews. */
+    submitReview?(ref: ChangeRequestRef, request: ForgeReviewRequest, signal: AbortSignal): Promise<ForgeReviewResult>;
     /** Map a Git remote URL to its repository, or undefined when this provider does not serve it. */
     repositoryFromRemote(url: string): ForgeRepository | undefined;
     /** Map a change request web URL to its reference, or undefined when this provider does not serve it. */
@@ -158,6 +190,8 @@ export interface ForgeProvider {
     changeRequestUrl(ref: ChangeRequestRef): string;
     /** Read the status of several change requests, returning one result per requested key. */
     fetch(refs: readonly ChangeRequestRef[], signal: AbortSignal): Promise<ReadonlyMap<ChangeRequestKey, ChangeRequestSnapshot | ForgeFailure>>;
+    /** Read all checks for one change request on demand; omission declares that only the polling preview is available. */
+    fetchChecks?(ref: ChangeRequestRef, signal: AbortSignal): Promise<ChangeRequestSnapshot | ForgeFailure>;
     /** Find open change requests whose head is `branch` in `repository`, excluding the default branch and forks. */
     findByHead(repository: ForgeRepository, branch: string, signal: AbortSignal): Promise<readonly ChangeRequestRef[]>;
     /** Report whether the provider can reach `host` with current credentials. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-experimental-forge",
   "description": "Provider-neutral change request registry with shared status polling",
-  "version": "0.2.2-alpha.2",
+  "version": "0.2.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -32,14 +32,14 @@
     "directory": "packages/experimental/forge"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "~3.18.6-alpha.1",
-    "@deepseek-ai/dsh-brand": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-timeout": "0.2.2-alpha.2"
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.2",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-timeout": "0.2.2-alpha.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
   }
 }