@compforge/harness-common 0.5.7 → 0.5.9

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

@@ -1,6 +1,10 @@
 import type { Identity } from "../identity.js";
-import { type Repository } from "./repository.js";
+import { type Repository, type RepositoryKey, type RepositorySnapshot } from "./repository.js";
 export type PullRequestState = "open" | "merged" | "closed";
+/** Code conflict facts do not establish permission/readiness to merge, or a completed merge. */
+export type PullRequestConflictState = "none" | "conflicted" | "unknown";
+/** Provider-reported merge conditions at observation time, not authorization for a merge operation. */
+export type PullRequestMergeReadiness = "ready" | "conflict" | "discussions_unresolved" | "ci_blocked" | "needs_approval" | "draft" | "behind" | "blocked" | "unknown";
 /**
  * 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.
@@ -14,6 +18,9 @@ export interface PullRequest extends Identity {
     readonly title?: string;
     readonly url?: string;
     readonly state?: PullRequestState;
+    /** Independent transient facts; neither implies state=merged. */
+    readonly conflictState?: PullRequestConflictState;
+    readonly mergeReadiness?: PullRequestMergeReadiness;
     readonly sourceRepository?: Repository;
     readonly sourceBranch?: string;
     readonly targetBranch?: string;
@@ -23,5 +30,19 @@ export interface PullRequest extends Identity {
     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(pr: Pick<PullRequest, "repository" | "number">): string;
+export declare function pullRequestId<T extends PullRequestKey>(pr: T): string;

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.7",
+  "version": "0.5.9",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {