@compforge/harness-common 0.5.6 → 0.5.8

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,41 @@
+import type { Identity } from "../identity.js";
+import { type Repository, type RepositoryKey, type RepositorySnapshot } 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;
+}
+/** The target Repository and its local PR number / MR iid; no methods or observation facts are required. */
+export interface PullRequestKey {
+    readonly repository: RepositoryKey;
+    readonly number: PullRequest["number"];
+}
+/**
+ * @spec A PR snapshot retains the common field names and optional facts, without PR or nested Repository identity methods.
+ * @why JSON and remote observations must not require each consumer to invent a parallel PR shape or reconstruct methods.
+ * @see {@link component://docs/pull-request.md}
+ */
+export type PullRequestSnapshot = Omit<PullRequest, "id" | "repository" | "sourceRepository"> & {
+    readonly repository: RepositorySnapshot;
+    readonly sourceRepository?: RepositorySnapshot;
+};
+/** Derive identity from fields; never trust a consumer's display URL or repository id method. */
+export declare function pullRequestId<T extends PullRequestKey>(pr: T): 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/dist/system/repository.d.ts

@@ -14,8 +14,12 @@ export interface Repository extends Identity {
      */
     readonly forkedFrom?: string | null;
 }
+/** Identity fields usable without constructing an in-process Repository. */
+export type RepositoryKey = Pick<Repository, "forge" | "path">;
+/** Repository facts carried by JSON, storage and remote observations; identity methods are not data. */
+export type RepositorySnapshot = Omit<Repository, "id">;
 /**
  * Derive the Repository.id() value from identity fields.
  * @spec Repository identity is forge.name/path; fork provenance is excluded.
  */
-export declare function repositoryId(repository: Pick<Repository, "forge" | "path">): string;
+export declare function repositoryId(repository: RepositoryKey): string;

package/package.json

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