ghagga-forge 3.1.0

package/dist/ports/forge-adapter.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The forge adapter port.
+ *
+ * A {@link ForgeAdapter} is what the core review engine talks to instead of any
+ * concrete forge SDK. {@link ForgeAdapterBase} is the mandatory surface every
+ * adapter MUST implement; optional capabilities are factored into discrete
+ * sub-interfaces composed onto the base via `Partial<>`.
+ *
+ * R-CAPABILITY (the load-bearing rule of this file):
+ * - Optional methods are guarded at runtime by METHOD PRESENCE
+ *   (`'fetchGraph' in adapter`), NEVER by the {@link ForgeCapabilities} flags.
+ * - The `capabilities` field is a HINT for planning/UI only. A misconfigured
+ *   flag must never cause a missing method to be invoked (TypeError) nor a
+ *   present method to be skipped.
+ * - Sub-interfaces exist so that, once you DO narrow via `'m' in adapter`, TS
+ *   gives you the full co-present method set of that capability (e.g. narrowing
+ *   on `fetchGraph` co-presence is expressed by the {@link GraphReadCapable}
+ *   interface owning BOTH graph methods).
+ * - Co-presence of the TWO graph methods is enforced AT THE TYPE LEVEL by the
+ *   union `GraphReadCapable | { fetchGraph?: never; fetchGraphMetadata?: never }`
+ *   in {@link ForgeAdapter}: an object may have BOTH graph methods or NEITHER,
+ *   but never exactly one. (`Partial<GraphReadCapable>` would NOT enforce this —
+ *   it would permit `fetchGraph` without `fetchGraphMetadata`.) Single-method
+ *   capabilities stay `Partial<>` because co-presence is trivial for one method.
+ */
+import type { DependencyGraph, GraphMetadata } from 'ghagga-core';
+import type { ChangedFile, ChangeRequest, ChangeRequestRef, CommentId, CommentMarker, Commit, ForgeCapabilities, PublishReport, RepoRef, UnifiedDiff, UpsertSummaryResult } from '../types.js';
+/** Kinds of reactions an adapter may support. */
+export declare const REACTION_KIND: {
+    readonly THUMBS_UP: "+1";
+    readonly THUMBS_DOWN: "-1";
+    readonly EYES: "eyes";
+    readonly ROCKET: "rocket";
+    readonly CONFUSED: "confused";
+};
+export type ReactionKind = (typeof REACTION_KIND)[keyof typeof REACTION_KIND];
+/**
+ * A single line-anchored inline comment to publish.
+ *
+ * PUBLIC API (R-LEAK-PUBLISH). This shape is intentionally ANCHORABLE so the
+ * GitLab discussion API (and a future GitHub inline-review impl) can be satisfied
+ * WITHOUT a breaking change:
+ * - `path` + `line` + `side` cover the common single-revision anchor (GitHub maps
+ *   `side` → LEFT/RIGHT; GitLab maps `side` → old_line/new_line).
+ * - `position` carries the GitLab diff-thread anchor (base/head/start SHAs +
+ *   old/new line). When present, the GitLab v1 adapter USES it toward the
+ *   discussions API for a true diff-thread; when absent it degrades to a
+ *   `path:line` body-prefixed plain note.
+ * - `oldPath`/`newPath` make RENAMES representable (GitLab requires BOTH
+ *   `position[old_path]` and `position[new_path]` for text diff notes). When
+ *   unset the adapter falls back to `path` for both — correct for non-renamed
+ *   files.
+ */
+export interface InlineComment {
+    /** File the comment anchors to (the post-change path for a renamed file). */
+    path: string;
+    /** Line number (in the diff's head/new revision unless `side` says otherwise). */
+    line: number;
+    /**
+     * Which side of the diff the line is on. `'new'` (default) → added/context
+     * line on the head revision; `'old'` → a line on the base revision.
+     */
+    side?: 'old' | 'new';
+    /**
+     * Pre-change path, for a RENAMED file. GitLab text diff notes require both the
+     * old and new path; when set, the adapter sends `position[old_path]`. Defaults
+     * to `path` when unset.
+     */
+    oldPath?: string;
+    /**
+     * Post-change path, for a RENAMED file. Defaults to `path` when unset. Carried
+     * so a future impl never needs an API change to support renames.
+     */
+    newPath?: string;
+    /**
+     * Full GitLab-style diff-thread anchor. When present, the GitLab v1 adapter
+     * uses it toward the discussions API (`position[position_type]=text`, the three
+     * SHAs, plus `old_line`/`new_line`). When absent, the adapter degrades to a
+     * plain note carrying the `path:line` prefix in the body.
+     */
+    position?: {
+        /** Merge-base / comparison base SHA (GitLab `position[base_sha]`). */
+        baseSha: string;
+        /** Head SHA of the change request (GitLab `position[head_sha]`). */
+        headSha: string;
+        /** Start SHA (GitLab `position[start_sha]`). */
+        startSha: string;
+        /** Line on the base revision (GitLab `position[old_line]`). */
+        oldLine?: number;
+        /** Line on the head revision (GitLab `position[new_line]`). */
+        newLine?: number;
+    };
+    /** Comment body (markdown). */
+    body: string;
+}
+/**
+ * Mandatory surface every forge adapter MUST implement.
+ *
+ * The methods here are the irreducible operations the review pipeline needs:
+ * read the diff, read change-request metadata, read the file list, read commits,
+ * and idempotently upsert the single summary comment.
+ */
+export interface ForgeAdapterBase {
+    /**
+     * Declarative capability hints. READONLY and HINT-ONLY — never use these as
+     * the runtime guard for an optional method (R-CAPABILITY).
+     */
+    readonly capabilities: ForgeCapabilities;
+    /** Fetch the unified diff for a change request. */
+    fetchDiff(ref: ChangeRequestRef): Promise<UnifiedDiff>;
+    /** Fetch change-request metadata (head SHA, base branch, author). */
+    fetchChangeRequest(ref: ChangeRequestRef): Promise<ChangeRequest>;
+    /** Fetch the list of changed files. */
+    fetchFileList(ref: ChangeRequestRef): Promise<ChangedFile[]>;
+    /** Fetch the commits in the change request. */
+    fetchCommits(ref: ChangeRequestRef): Promise<Commit[]>;
+    /**
+     * Idempotently upsert the single GHAGGA summary comment.
+     *
+     * The `marker` identifies prior GHAGGA summary comments so they can be cleaned
+     * up; the result reports the surviving comment and any deleted stale ones.
+     */
+    upsertSummaryComment(ref: ChangeRequestRef, body: string, marker: CommentMarker): Promise<UpsertSummaryResult>;
+}
+/** Optional: adapter can add reactions to comments. */
+export interface ReactionCapable {
+    /** Add a reaction to a comment. */
+    addReaction(commentId: CommentId, reaction: ReactionKind): Promise<void>;
+}
+/**
+ * Optional: adapter can READ a dependency graph for a repo.
+ *
+ * R-GRAPH: this is the typed graph-READ seam. The two methods are co-present:
+ * {@link ForgeAdapter} composes this interface as an all-or-nothing union, so an
+ * adapter has BOTH methods or NEITHER — never exactly one. Graph WRITE is
+ * GitHub-only and
+ * is deliberately NOT part of the adapter surface (deferred to P5). Returns of
+ * `null` mean "no graph available" — distinct from "graph read unsupported"
+ * (which is method absence).
+ */
+export interface GraphReadCapable {
+    /** Read the full dependency graph, or null if none is available. */
+    fetchGraph(repo: RepoRef): Promise<DependencyGraph | null>;
+    /** Read graph metadata (freshness, size, …), or null if none is available. */
+    fetchGraphMetadata(repo: RepoRef): Promise<GraphMetadata | null>;
+}
+/** Optional: adapter can publish line-anchored inline comments. */
+export interface InlineCapable {
+    /** Publish a batch of inline comments; partial success is reported. */
+    publishInline(ref: ChangeRequestRef, comments: InlineComment[]): Promise<PublishReport>;
+}
+/** Optional: adapter can extract a marker payload from a comment body. */
+export interface MarkerExtractable {
+    /**
+     * Extract the payload embedded behind `marker` in `body`, or null if the
+     * marker is not present.
+     */
+    extractMarker(body: string, marker: CommentMarker): string | null;
+}
+/**
+ * The full adapter type the engine consumes.
+ *
+ * Base is mandatory; single-method capabilities are `Partial<>`-composed so an
+ * adapter can implement any subset. The graph capability is composed as an
+ * all-or-nothing union so an adapter cannot have exactly one of the two graph
+ * methods (type-level co-presence; see R-GRAPH and the header note). Consumers
+ * MUST narrow optional capabilities via method-presence (`'fetchGraph' in
+ * adapter`) before calling — see R-CAPABILITY at the top of this file.
+ */
+export type ForgeAdapter = ForgeAdapterBase & Partial<ReactionCapable> & (GraphReadCapable | {
+    fetchGraph?: never;
+    fetchGraphMetadata?: never;
+}) & Partial<InlineCapable> & Partial<MarkerExtractable>;
+//# sourceMappingURL=forge-adapter.d.ts.map

package/dist/ports/forge-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge-adapter.d.ts","sourceRoot":"","sources":["../../src/ports/forge-adapter.ts"],"names":[],"mappings":"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"}

package/dist/ports/forge-adapter.js

@@ -0,0 +1,34 @@
+/**
+ * The forge adapter port.
+ *
+ * A {@link ForgeAdapter} is what the core review engine talks to instead of any
+ * concrete forge SDK. {@link ForgeAdapterBase} is the mandatory surface every
+ * adapter MUST implement; optional capabilities are factored into discrete
+ * sub-interfaces composed onto the base via `Partial<>`.
+ *
+ * R-CAPABILITY (the load-bearing rule of this file):
+ * - Optional methods are guarded at runtime by METHOD PRESENCE
+ *   (`'fetchGraph' in adapter`), NEVER by the {@link ForgeCapabilities} flags.
+ * - The `capabilities` field is a HINT for planning/UI only. A misconfigured
+ *   flag must never cause a missing method to be invoked (TypeError) nor a
+ *   present method to be skipped.
+ * - Sub-interfaces exist so that, once you DO narrow via `'m' in adapter`, TS
+ *   gives you the full co-present method set of that capability (e.g. narrowing
+ *   on `fetchGraph` co-presence is expressed by the {@link GraphReadCapable}
+ *   interface owning BOTH graph methods).
+ * - Co-presence of the TWO graph methods is enforced AT THE TYPE LEVEL by the
+ *   union `GraphReadCapable | { fetchGraph?: never; fetchGraphMetadata?: never }`
+ *   in {@link ForgeAdapter}: an object may have BOTH graph methods or NEITHER,
+ *   but never exactly one. (`Partial<GraphReadCapable>` would NOT enforce this —
+ *   it would permit `fetchGraph` without `fetchGraphMetadata`.) Single-method
+ *   capabilities stay `Partial<>` because co-presence is trivial for one method.
+ */
+/** Kinds of reactions an adapter may support. */
+export const REACTION_KIND = {
+    THUMBS_UP: '+1',
+    THUMBS_DOWN: '-1',
+    EYES: 'eyes',
+    ROCKET: 'rocket',
+    CONFUSED: 'confused',
+};
+//# sourceMappingURL=forge-adapter.js.map

package/dist/ports/forge-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge-adapter.js","sourceRoot":"","sources":["../../src/ports/forge-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAqBH,iDAAiD;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,SAAS,EAAE,IAAI;IACf,WAAW,EAAE,IAAI;IACjB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/ports/webhook-codec.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The forge webhook codec port (task 0.5) — INTERFACE SHAPE ONLY.
+ *
+ * Two-phase design:
+ *   1. identify(headers, raw)  → cheap, pre-verification tenant routing. Returns
+ *      a {@link TenantHint} (or null) so the host can pick the right secret /
+ *      credentials before trusting anything.
+ *   2. verify(payload, headers, secret) → authenticate the payload signature.
+ *   3. parse(payload, headers) → normalize into a forge-agnostic {@link ForgeEvent}.
+ *
+ * NEEDS GUARD (P5): the verify-before-parse ordering guarantee is INTENTIONALLY
+ * DEFERRED to P5. This interface only declares the shape — it does NOT yet
+ * enforce, at the type level or runtime, that `verify` was called (and returned
+ * true) before `parse`. P5 will add that guard. Do NOT assume parse is safe to
+ * call on unverified input in the meantime.
+ */
+import type { ForgeEvent, TenantHint } from '../types.js';
+/** Decodes and authenticates incoming forge webhooks. */
+export interface ForgeWebhookCodec {
+    /**
+     * Phase 1: extract a tenant-routing hint WITHOUT trusting the payload.
+     *
+     * Runs before signature verification so the host can select the correct
+     * secret/credentials. Returns null when the webhook cannot be routed.
+     */
+    identify(headers: Record<string, string>, raw: string): TenantHint | null;
+    /**
+     * Phase 2: verify the payload signature against `secret`.
+     *
+     * @returns true iff the payload is authentic.
+     */
+    verify(payload: unknown, headers: Record<string, string>, secret: string): boolean;
+    /**
+     * Phase 3: normalize a (verified) payload into a forge-agnostic event.
+     *
+     * NEEDS GUARD (P5): nothing here yet enforces that {@link verify} succeeded
+     * first — that guard lands in P5.
+     */
+    parse(payload: unknown, headers: Record<string, string>): ForgeEvent;
+}
+//# sourceMappingURL=webhook-codec.d.ts.map

package/dist/ports/webhook-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-codec.d.ts","sourceRoot":"","sources":["../../src/ports/webhook-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAE1E;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAEnF;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,UAAU,CAAC;CACtE"}

package/dist/ports/webhook-codec.js

@@ -0,0 +1,18 @@
+/**
+ * The forge webhook codec port (task 0.5) — INTERFACE SHAPE ONLY.
+ *
+ * Two-phase design:
+ *   1. identify(headers, raw)  → cheap, pre-verification tenant routing. Returns
+ *      a {@link TenantHint} (or null) so the host can pick the right secret /
+ *      credentials before trusting anything.
+ *   2. verify(payload, headers, secret) → authenticate the payload signature.
+ *   3. parse(payload, headers) → normalize into a forge-agnostic {@link ForgeEvent}.
+ *
+ * NEEDS GUARD (P5): the verify-before-parse ordering guarantee is INTENTIONALLY
+ * DEFERRED to P5. This interface only declares the shape — it does NOT yet
+ * enforce, at the type level or runtime, that `verify` was called (and returned
+ * true) before `parse`. P5 will add that guard. Do NOT assume parse is safe to
+ * call on unverified input in the meantime.
+ */
+export {};
+//# sourceMappingURL=webhook-codec.js.map

package/dist/ports/webhook-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-codec.js","sourceRoot":"","sources":["../../src/ports/webhook-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/project.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Sanctioned projection helpers (task 0.6).
+ *
+ * These three functions are the ONLY blessed way to project forge-agnostic
+ * domain objects into the shapes the core review engine consumes. Centralizing
+ * the projections keeps the wrong-field bug class (R-PROJECTION) in exactly one
+ * auditable place.
+ *
+ * R-PROJECTION (load-bearing): {@link toCommitMessages} MUST map each commit's
+ * `.message`, NEVER its `.sha`. A `.sha` projection type-checks perfectly
+ * (both are `string`) yet silently feeds 40-char hashes to the LLM instead of
+ * commit messages — a correctness bug invisible to the type system. The unit
+ * test in `project.test.ts` pins `.message !== .sha` to catch any regression.
+ */
+import type { ReviewContext } from 'ghagga-core';
+import type { ChangedFile, Commit } from './types.js';
+/**
+ * Project commits into the commit-message strings the engine reviews.
+ *
+ * R-PROJECTION: maps `.message` (NOT `.sha`).
+ */
+export declare function toCommitMessages(commits: Commit[]): string[];
+/** Project changed files into the flat path list the engine consumes. */
+export declare function toFileList(files: ChangedFile[]): string[];
+/**
+ * Assemble the core {@link ReviewContext} from forge-agnostic inputs.
+ *
+ * Uses {@link toCommitMessages} and {@link toFileList} internally so the
+ * projection rules are applied consistently.
+ */
+export declare function toReviewContext(repoFullName: string, prNumber: number, commits: Commit[], files: ChangedFile[]): ReviewContext;
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE5D;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,WAAW,EAAE,GACnB,aAAa,CAOf"}

package/dist/project.js

@@ -0,0 +1,41 @@
+/**
+ * Sanctioned projection helpers (task 0.6).
+ *
+ * These three functions are the ONLY blessed way to project forge-agnostic
+ * domain objects into the shapes the core review engine consumes. Centralizing
+ * the projections keeps the wrong-field bug class (R-PROJECTION) in exactly one
+ * auditable place.
+ *
+ * R-PROJECTION (load-bearing): {@link toCommitMessages} MUST map each commit's
+ * `.message`, NEVER its `.sha`. A `.sha` projection type-checks perfectly
+ * (both are `string`) yet silently feeds 40-char hashes to the LLM instead of
+ * commit messages — a correctness bug invisible to the type system. The unit
+ * test in `project.test.ts` pins `.message !== .sha` to catch any regression.
+ */
+/**
+ * Project commits into the commit-message strings the engine reviews.
+ *
+ * R-PROJECTION: maps `.message` (NOT `.sha`).
+ */
+export function toCommitMessages(commits) {
+    return commits.map((commit) => commit.message);
+}
+/** Project changed files into the flat path list the engine consumes. */
+export function toFileList(files) {
+    return files.map((file) => file.path);
+}
+/**
+ * Assemble the core {@link ReviewContext} from forge-agnostic inputs.
+ *
+ * Uses {@link toCommitMessages} and {@link toFileList} internally so the
+ * projection rules are applied consistently.
+ */
+export function toReviewContext(repoFullName, prNumber, commits, files) {
+    return {
+        repoFullName,
+        prNumber,
+        commitMessages: toCommitMessages(commits),
+        fileList: toFileList(files),
+    };
+}
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAiB;IAChD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAoB,EACpB,QAAgB,EAChB,OAAiB,EACjB,KAAoB;IAEpB,OAAO;QACL,YAAY;QACZ,QAAQ;QACR,cAAc,EAAE,gBAAgB,CAAC,OAAO,CAAC;QACzC,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC;KAC5B,CAAC;AACJ,CAAC"}

package/dist/ref.d.ts

@@ -0,0 +1,20 @@
+/**
+ * RepoRef identity helpers.
+ *
+ * R-COMMENTID family / IDENTITY RULE: two repositories are the same iff their
+ * `kind` AND `nativeId` match. `path` is a mutable human-friendly label (repos
+ * get renamed/transferred) and MUST NOT participate in identity comparison.
+ */
+import type { RepoRef } from './types.js';
+/**
+ * Structural identity for {@link RepoRef}.
+ *
+ * Keys on `kind` + `nativeId` and DELIBERATELY ignores `path` (mutable label).
+ * This is the contract every consumer (registry, dedup, caching) relies on.
+ *
+ * @param a first repo reference.
+ * @param b second repo reference.
+ * @returns true iff `a` and `b` denote the same repository.
+ */
+export declare function repoRefEquals(a: RepoRef, b: RepoRef): boolean;
+//# sourceMappingURL=ref.d.ts.map

package/dist/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../src/ref.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAE7D"}

package/dist/ref.js

@@ -0,0 +1,21 @@
+/**
+ * RepoRef identity helpers.
+ *
+ * R-COMMENTID family / IDENTITY RULE: two repositories are the same iff their
+ * `kind` AND `nativeId` match. `path` is a mutable human-friendly label (repos
+ * get renamed/transferred) and MUST NOT participate in identity comparison.
+ */
+/**
+ * Structural identity for {@link RepoRef}.
+ *
+ * Keys on `kind` + `nativeId` and DELIBERATELY ignores `path` (mutable label).
+ * This is the contract every consumer (registry, dedup, caching) relies on.
+ *
+ * @param a first repo reference.
+ * @param b second repo reference.
+ * @returns true iff `a` and `b` denote the same repository.
+ */
+export function repoRefEquals(a, b) {
+    return a.kind === b.kind && a.nativeId === b.nativeId;
+}
+//# sourceMappingURL=ref.js.map

package/dist/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../src/ref.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,CAAU,EAAE,CAAU;IAClD,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,CAAC;AACxD,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The adapter registry (task 0.7).
+ *
+ * Resolves a {@link ForgeAdapter} from a {@link RepoRef} by its `kind`. A lookup
+ * miss is a TYPED failure (R-RESOLVE): {@link ForgeRegistry.resolve} throws
+ * {@link UnknownForgeError} rather than returning `undefined` and letting a
+ * caller blow up later on `undefined.fetchDiff(...)`.
+ */
+import type { ForgeAdapter } from './ports/forge-adapter.js';
+import type { ForgeKind, RepoRef } from './types.js';
+/**
+ * Optional diagnostic context attached to an {@link UnknownForgeError}.
+ *
+ * Purely additive — the error remains constructible with just a `kind`. When the
+ * registry raises it, it fills in the kinds it DOES know about (and the repo, if
+ * available) so the failure message is self-diagnosing instead of just naming
+ * the missing kind.
+ */
+export interface UnknownForgeErrorContext {
+    /** Forge kinds that DO have a registered adapter at throw time. */
+    registeredKinds?: readonly ForgeKind[];
+    /** The repo whose resolution failed, when available. */
+    repo?: RepoRef;
+}
+/**
+ * Thrown when the registry has no adapter registered for a repo's forge kind.
+ *
+ * R-RESOLVE: a typed, named error — callers can `instanceof`-narrow it instead
+ * of guessing why an adapter was `undefined`.
+ */
+export declare class UnknownForgeError extends Error {
+    /** The forge kind that had no registered adapter. */
+    readonly kind: ForgeKind;
+    /** Forge kinds that DID have a registered adapter at throw time, if known. */
+    readonly registeredKinds?: readonly ForgeKind[];
+    /** The repo whose resolution failed, if available. */
+    readonly repo?: RepoRef;
+    constructor(kind: ForgeKind, context?: UnknownForgeErrorContext);
+}
+/** Looks up forge adapters by forge kind. */
+export interface ForgeRegistry {
+    /**
+     * Register an adapter for a forge kind. A later registration for the same kind
+     * overrides the earlier one.
+     */
+    register(kind: ForgeKind, adapter: ForgeAdapter): void;
+    /** Whether an adapter is registered for `kind`. */
+    has(kind: ForgeKind): boolean;
+    /**
+     * Resolve the adapter for `repo.kind`.
+     *
+     * @throws {UnknownForgeError} when no adapter is registered for the kind.
+     */
+    resolve(repo: RepoRef): ForgeAdapter;
+}
+/**
+ * In-memory {@link ForgeRegistry}.
+ *
+ * The default registry implementation: a simple `Map` keyed by forge kind.
+ * `resolve` is where R-RESOLVE lives — a miss throws {@link UnknownForgeError},
+ * never returns `undefined`.
+ */
+export declare class MapForgeRegistry implements ForgeRegistry {
+    private readonly adapters;
+    register(kind: ForgeKind, adapter: ForgeAdapter): void;
+    has(kind: ForgeKind): boolean;
+    resolve(repo: RepoRef): ForgeAdapter;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,eAAe,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAChD,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,wBAAwB;CAoBhE;AAED,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAEvD,mDAAmD;IACnD,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAE9B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAAC;CACtC;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAItD,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAI7B,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY;CAUrC"}

package/dist/registry.js

@@ -0,0 +1,68 @@
+/**
+ * The adapter registry (task 0.7).
+ *
+ * Resolves a {@link ForgeAdapter} from a {@link RepoRef} by its `kind`. A lookup
+ * miss is a TYPED failure (R-RESOLVE): {@link ForgeRegistry.resolve} throws
+ * {@link UnknownForgeError} rather than returning `undefined` and letting a
+ * caller blow up later on `undefined.fetchDiff(...)`.
+ */
+/**
+ * Thrown when the registry has no adapter registered for a repo's forge kind.
+ *
+ * R-RESOLVE: a typed, named error — callers can `instanceof`-narrow it instead
+ * of guessing why an adapter was `undefined`.
+ */
+export class UnknownForgeError extends Error {
+    /** The forge kind that had no registered adapter. */
+    kind;
+    /** Forge kinds that DID have a registered adapter at throw time, if known. */
+    registeredKinds;
+    /** The repo whose resolution failed, if available. */
+    repo;
+    constructor(kind, context) {
+        const known = context?.registeredKinds;
+        const knownSuffix = known === undefined
+            ? ''
+            : known.length === 0
+                ? ' (no adapters are registered)'
+                : ` (registered: ${known.map((k) => `"${k}"`).join(', ')})`;
+        super(`No forge adapter registered for kind "${kind}"${knownSuffix}`);
+        this.name = 'UnknownForgeError';
+        this.kind = kind;
+        if (context?.registeredKinds !== undefined) {
+            this.registeredKinds = context.registeredKinds;
+        }
+        if (context?.repo !== undefined) {
+            this.repo = context.repo;
+        }
+        // Preserve prototype chain across down-level transpilation targets.
+        Object.setPrototypeOf(this, UnknownForgeError.prototype);
+    }
+}
+/**
+ * In-memory {@link ForgeRegistry}.
+ *
+ * The default registry implementation: a simple `Map` keyed by forge kind.
+ * `resolve` is where R-RESOLVE lives — a miss throws {@link UnknownForgeError},
+ * never returns `undefined`.
+ */
+export class MapForgeRegistry {
+    adapters = new Map();
+    register(kind, adapter) {
+        this.adapters.set(kind, adapter);
+    }
+    has(kind) {
+        return this.adapters.has(kind);
+    }
+    resolve(repo) {
+        const adapter = this.adapters.get(repo.kind);
+        if (adapter === undefined) {
+            throw new UnknownForgeError(repo.kind, {
+                registeredKinds: [...this.adapters.keys()],
+                repo,
+            });
+        }
+        return adapter;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoBH;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,qDAAqD;IAC5C,IAAI,CAAY;IACzB,8EAA8E;IACrE,eAAe,CAAwB;IAChD,sDAAsD;IAC7C,IAAI,CAAW;IAExB,YAAY,IAAe,EAAE,OAAkC;QAC7D,MAAM,KAAK,GAAG,OAAO,EAAE,eAAe,CAAC;QACvC,MAAM,WAAW,GACf,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;gBAClB,CAAC,CAAC,+BAA+B;gBACjC,CAAC,CAAC,iBAAiB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAClE,KAAK,CAAC,yCAAyC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,EAAE,eAAe,KAAK,SAAS,EAAE,CAAC;YAC3C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QACjD,CAAC;QACD,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3B,CAAC;QACD,oEAAoE;QACpE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;CACF;AAqBD;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACV,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE/D,QAAQ,CAAC,IAAe,EAAE,OAAqB;QAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IAED,GAAG,CAAC,IAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,CAAC,IAAa;QACnB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE;gBACrC,eAAe,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAC1C,IAAI;aACL,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}