@compforge/harness-common 0.5.6 → 0.5.7

package/README.md

@@ -183,3 +183,10 @@ custom Entry now renders consistently when shown alone or through its Dictionary
 relationships without duplicating identity. `ResourceSnapshot` retains typed instances, unit-bearing
 measurements, independently known totals and complete/partial/unavailable coverage. Discovery and
 rendering remain consumer-owned. See [the shared contract](../../../docs/resource.md).
+
+## PullRequest
+
+`PullRequest` identifies a PR/MR by its target `Repository` and repository-local number.
+State, branches, source repository, revisions and provider timestamps are optional facts.
+See [the shared contract](../../../docs/pull-request.md) for identity and unknown-state semantics.
+Forge access and polling remain consumer/toolkit responsibilities.

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./access/datasource.js";
 export * from "./system/workload.js";
 export * from "./system/forge.js";
 export * from "./system/repository.js";
+export * from "./system/pull-request.js";
 export * from "./system/component.js";
 export * from "./system/host.js";
 export * from "./system/environment.js";

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./access/datasource.js";
 export * from "./system/workload.js";
 export * from "./system/forge.js";
 export * from "./system/repository.js";
+export * from "./system/pull-request.js";
 export * from "./system/component.js";
 export * from "./system/host.js";
 export * from "./system/environment.js";

package/dist/system/pull-request.d.ts

@@ -0,0 +1,27 @@
+import type { Identity } from "../identity.js";
+import { type Repository } from "./repository.js";
+export type PullRequestState = "open" | "merged" | "closed";
+/**
+ * A code-review proposal owned by its target Repository (GitHub PR or GitLab MR).
+ * @spec Identity is target Repository + repository-local number; source, revisions and state are metadata.
+ * @spec Omitted facts are unknown. A missing state or mergedAt never proves closure or merge.
+ * @see {@link component://docs/pull-request.md}
+ */
+export interface PullRequest extends Identity {
+    readonly repository: Repository;
+    /** Positive GitHub PR number or GitLab MR iid, not the provider's global database ID. */
+    readonly number: number;
+    readonly title?: string;
+    readonly url?: string;
+    readonly state?: PullRequestState;
+    readonly sourceRepository?: Repository;
+    readonly sourceBranch?: string;
+    readonly targetBranch?: string;
+    readonly headSha?: string;
+    readonly baseSha?: string;
+    /** Provider timestamps, represented as ISO 8601 strings. */
+    readonly updatedAt?: string;
+    readonly mergedAt?: string;
+}
+/** Derive identity from fields; never trust a consumer's display URL or repository id method. */
+export declare function pullRequestId(pr: Pick<PullRequest, "repository" | "number">): string;

package/dist/system/pull-request.js

@@ -0,0 +1,5 @@
+import { repositoryId } from "./repository.js";
+/** Derive identity from fields; never trust a consumer's display URL or repository id method. */
+export function pullRequestId(pr) {
+    return `${repositoryId(pr.repository)}#${pr.number}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-common",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {