@effect-agent/pr-review 0.0.1-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel van der Merwe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @effect-agent/pr-review
+
+A bounded, fail-closed GitHub pull-request reviewer built on the effect-agent
+public surface. One read-only Agent reviews a pull request through typed
+ports; the host validates every finding anchor against the real diff and
+posts one review after the run settles.
+
+**Deployment class E (ephemeral).** One `AgentRuntime.run` per invocation, no
+durability claim, and review posting is never exactly-once: a failed or
+truncated run posts nothing.
+
+## Use
+
+```ts
+import { Effect, Layer } from "effect";
+import {
+  PrReview,
+  gitHubReviewLayers,
+  resolveReviewTarget,
+  makeOpenAiReviewModel,
+  openAiClientLayer,
+} from "@effect-agent/pr-review";
+
+const reviewer = PrReview.make({ model: makeOpenAiReviewModel() });
+
+const program = Effect.gen(function* () {
+  const target = yield* resolveReviewTarget({ repository: "acme/api", number: 123 });
+  return yield* reviewer
+    .run({ post: true })
+    .pipe(Effect.provide(Layer.merge(gitHubReviewLayers(target), openAiClientLayer)));
+});
+```
+
+The run's requirement channel keeps every real dependency visible: the
+`PullRequestSource` and `ReviewPublisher` ports, the provider client, and the
+handler Layer of any extra tool you add. Anthropic is equally supported
+(`makeAnthropicReviewModel`, `anthropicClientLayer`), and the factory accepts
+any Effect AI Model.
+
+## Adapt
+
+```ts
+const reviewer = PrReview.make({
+  model: makeAnthropicReviewModel("claude-sonnet-5"),
+  guidance: (mission) => [
+    "This is an Effect codebase. Flag naked Promises in public APIs.",
+    mission.changedFileCount > 50 ? "Large PR: prioritize breadth over nit depth." : "",
+  ],
+  ignore: ["**/*.lock", "dist/**"],
+  maxFindings: 10,
+  policy: { maxTurns: 20, maxToolCalls: 40, maxDuration: "10 minutes", toolConcurrency: 2 },
+  extraTools: [MyReadonlyTool], // must be annotated ToolExecutionClass "readonly"
+});
+```
+
+Every knob widens what goes INTO the review. What leaves it is not
+configurable: model output is untrusted input, so finding anchors are
+re-validated against the parsed unified diff (invalid ones are demoted into
+the review body with the reason named, never trusted), the findings bound is
+enforced host-side, and publication happens only through the
+`ReviewPublisher` port after the run settles. `PrReview.makeFanOut` builds
+the delegating variant — bounded per-unit child reviewers (S1 attached
+ephemeral delegation) merged under the same output contract and the same
+publication path; the shared `guidance` and `maxFindings` shape the
+coordinator's merge as well as the children.
+
+## What a posted review looks like
+
+The body opens with a host-derived callout tier — `[!CAUTION]` when any
+finding is blocking, `[!IMPORTANT]` for important findings, an ℹ️ blockquote
+for nits, `✅` for a clean approval — computed from the validated severities,
+never from model prose. Below the summary, non-anchored `concerns` (deletion
+plans, rollout sequencing, coverage gaps, scope questions — things with no
+diff line to point at) render as severity-tagged sections. The footer names
+the model binding, the observed token usage, and links to the workflow run;
+an invisible metadata comment pins the reviewed head commit so later readers
+know when line callouts have gone stale.
+
+## Swap a port
+
+Tools observe the pull request only through `PullRequestSource`; publication
+happens only through `ReviewPublisher`. Provide your own Layers to review
+anything diff-shaped or publish anywhere else — the GitHub REST adapters are
+one implementation, not the contract.
+
+## Test what you adapted
+
+```ts
+import {
+  fixturePullRequestSourceLayer,
+  collectingReviewPublisherLayer,
+  makeOfflineReviewerModel,
+  makePromptKeyedModel,
+} from "@effect-agent/pr-review/testing";
+```
+
+Deterministic in-memory adapters for both ports plus prompt-keyed scripted
+models that walk the real tool surface — no network, no credentials, every
+ordinary gate.
+
+## Incremental Action reviews
+
+A completely covered posted Action review carries bounded, versioned,
+HMAC-authenticated continuity state:
+the exact PR/base/head lineage, profile and accepted-scope fingerprints, and
+the still-unresolved findings and concerns. A later Action run validates the
+state and reviews the GitHub comparison from that reviewed head to the
+current head, not the complete base...HEAD diff. Unchanged accepted scope is
+not sent back to the model; unchanged unresolved findings remain active;
+changed or reverted paths invalidate their prior findings. Non-anchored
+concerns are carried conservatively until a full audit because they cannot be
+mapped safely to one path.
+
+The state marker must be terminal, signed with the configured stable
+`PR_REVIEW_STATE_SECRET`, authored by the default GitHub Actions bot, and
+pinned to the reviewed commit. State lookup, authentication, schema, identity,
+ancestry, profile, and comparison checks are
+fail-closed for scope selection: missing, stale, incompatible, or truncated
+state/comparisons produce a visible full-diff fallback. An ancestor base
+advance remains incremental and adds overlapping PR paths as affected
+context; a materially changed base lineage falls back to full. Re-running the
+same covered head skips model execution by default while preserving its
+stored blocking/success conclusion.
+
+Authentication is an explicit Effect service supplied by the Action host;
+WebCrypto import/sign/verify failures stay typed. The terminal marker is
+schema-branded and capped at 24,000 characters. If signing fails or state
+exceeds that bound, the completed review is posted without continuity state
+and with a bounded warning, so the next run safely performs a full review.
+
+`review-mode: final` is the explicit bounded merge-readiness audit. It reviews
+the full current PR diff and resets the incremental baseline; normal
+`synchronize` events use `incremental` and do not perform this audit.
+
+## Hosts
+
+- **GitHub Actions**: the repository ships a prebuilt node-runtime action
+  supporting a committed review-profile document via `guidance-file` (this
+  repository's own profile lives at `.github/review-guidance.md`)
+  (`action/` at the repo root) — `uses` it with an API-key secret and nothing
+  else. For custom reviewers in CI, `@effect-agent/pr-review/action` exports
+  `runReviewAction` (event resolution, typed draft/non-PR skips, bounded range
+  selection, step outputs, and conservative check gate) to harness your own
+  `reviewer.run`.
+- **CLI**: `bun src/cli.ts --repo owner/name --pr 123 [--post] [--provider anthropic] [--fan-out]`
+  (also exported as the `./cli` entry).
+
+Environment: `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` for the model,
+`PR_REVIEW_STATE_SECRET` to authenticate incremental state,
+`GITHUB_TOKEN` to post (optional for public-repository reads), and the
+standard `GITHUB_REPOSITORY` / `GITHUB_EVENT_PATH` / `GITHUB_API_URL`
+variables inside Actions.
+
+## Bounds, spelled out
+
+Finite `AgentPolicy` on every definition plus run-level `UsageBudgetLimits`
+(tokens, tool calls, cost, duration). Reading a file head version beyond 200k
+characters is refused typed. The changeset surface is bounded at 300 files:
+files beyond the bound are not fetched, and the review body reports
+`Reviewed N of M changed files` instead of claiming completeness. Fan-out
+capacity overflow is reported in the review summary, never dropped. Any
+blocking active finding fails the Action check. Any required-file coverage
+gap — undiffable/unassigned paths, failed units (including policy exhaustion),
+truncation, or coordinator/run failure — is non-success rather than green.

package/dist/action.d.mts

@@ -0,0 +1,185 @@
+import { J as ReviewPublisher, K as PriorReviews, U as GitHubApiFailure, _n as ChangedFile, ct as ReviewMode, fn as PullRequestMetadata, mn as PullRequestSourceFailure, pn as PullRequestSource, pt as ReviewStateAuthenticator } from "./fan-out-Dy84-dIs.mjs";
+import { EffortPosition, InvalidEffortInput, ReviewProvider, ReviewRunOutcome, ReviewTargetUnresolved, RunReviewOptions } from "./index.mjs";
+import { Config, Effect, FileSystem, Schema } from "effect";
+import { BudgetExceeded } from "effect-agent";
+//#region src/action.d.ts
+/** Deprecated compatibility input; host-derived conclusions are unconditional. */
+declare const FailOnPolicy: Schema.Literals<readonly ["never", "request-changes"]>;
+type FailOnPolicy = typeof FailOnPolicy.Type;
+declare const ReviewCheckConclusion: Schema.Literals<readonly ["success", "blocking", "incomplete"]>;
+type ReviewCheckConclusion = typeof ReviewCheckConclusion.Type;
+declare const ReviewGateFailed_base: Schema.Class<ReviewGateFailed, Schema.TaggedStruct<"ReviewGateFailed", {
+  readonly conclusion: Schema.Literals<readonly ["blocking", "incomplete"]>;
+  readonly reasons: Schema.$Array<Schema.NonEmptyString>;
+}>, import("effect/Cause").YieldableError>;
+/** The host-derived blocking or incomplete conclusion failed the check. */
+declare class ReviewGateFailed extends ReviewGateFailed_base {
+  get message(): string;
+}
+declare const InvalidMaxDurationInput_base: Schema.Class<InvalidMaxDurationInput, Schema.TaggedStruct<"InvalidMaxDurationInput", {
+  readonly minutes: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** A configured max-duration that cannot bound a run; configuration faults fail loudly. */
+declare class InvalidMaxDurationInput extends InvalidMaxDurationInput_base {
+  get message(): string;
+}
+/** Everything the packaged action reads from its environment. */
+interface ResolvedActionInputs {
+  readonly provider: ReviewProvider;
+  readonly model: string | undefined;
+  readonly effort: EffortPosition | undefined;
+  readonly post: boolean;
+  readonly applyVerdict: boolean;
+  readonly fanOut: boolean;
+  readonly guidance: string | undefined;
+  readonly guidanceFile: string | undefined;
+  readonly ignore: ReadonlyArray<string>;
+  readonly maxFindings: number | undefined;
+  readonly maxDurationMinutes: number | undefined;
+  readonly reviewMode: ReviewMode;
+  /** Deprecated compatibility input; conclusions are always conservative. */
+  readonly failOn: FailOnPolicy;
+  readonly skipUnchanged: boolean;
+}
+/** Read the PR_REVIEW_* input surface (all optional, all defaulted). */
+declare const resolveActionInputs: () => Effect.Effect<{
+  provider: ReviewProvider;
+  model: string | undefined;
+  effort: number | undefined;
+  post: boolean;
+  applyVerdict: boolean;
+  fanOut: boolean;
+  guidance: string | undefined;
+  guidanceFile: string | undefined;
+  ignore: string[];
+  maxFindings: number | undefined;
+  maxDurationMinutes: number | undefined;
+  reviewMode: "final" | "incremental";
+  failOn: "never" | "request-changes";
+  skipUnchanged: boolean;
+}, Config.ConfigError | InvalidEffortInput | InvalidMaxDurationInput, never>;
+/** A guidance file larger than this is refused, never silently truncated. */
+declare const MAX_GUIDANCE_FILE_CHARS = 20000;
+declare const GuidanceFileUnreadable_base: Schema.Class<GuidanceFileUnreadable, Schema.TaggedStruct<"GuidanceFileUnreadable", {
+  readonly path: Schema.String;
+  readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A configured guidance file could not be used; configuration faults fail loudly. */
+declare class GuidanceFileUnreadable extends GuidanceFileUnreadable_base {
+  get message(): string;
+}
+/**
+ * Resolve the effective review guidance: the committed guidance file (a
+ * repository-owned review profile) first, with any inline guidance appended.
+ * A configured-but-unreadable file fails typed — a review silently running
+ * without its profile would be worse than a red job.
+ */
+declare const resolveGuidance: (inputs: {
+  readonly guidance: string | undefined;
+  readonly guidanceFile: string | undefined;
+}) => Effect.Effect<string | undefined, GuidanceFileUnreadable, FileSystem.FileSystem>;
+/** Append step outputs to GITHUB_OUTPUT when present (no-op locally). */
+declare const writeActionOutputs: (entries: readonly (readonly [name: string, value: string])[]) => Effect.Effect<void, Config.ConfigError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem>;
+/** Append markdown to the GITHUB_STEP_SUMMARY report when present (no-op locally). */
+declare const writeStepSummary: (lines: readonly string[]) => Effect.Effect<void, Config.ConfigError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem>;
+/** The result of one action invocation: a typed skip or a settled review. */
+type ReviewActionResult = {
+  readonly _tag: "Skipped";
+  readonly reason: string;
+} | {
+  readonly _tag: "Completed";
+  readonly outcome: ReviewRunOutcome;
+};
+/** The reviewer surface the action harness drives. `PrReview.make` and
+ * `PrReview.makeFanOut` provide the state-selection effects; the legacy
+ * fingerprint field remains for source compatibility with custom harnesses. */
+interface HarnessedReviewer<E, R, FingerprintE, FingerprintR> {
+  readonly run: (runOptions?: RunReviewOptions) => Effect.Effect<ReviewRunOutcome, E, R>;
+  readonly fingerprint?: Effect.Effect<string, FingerprintE, FingerprintR> | undefined;
+  readonly profileFingerprint?: Effect.Effect<string, FingerprintE, FingerprintR> | undefined;
+  readonly snapshot?: Effect.Effect<{
+    readonly metadata: PullRequestMetadata;
+    readonly files: ReadonlyArray<ChangedFile>;
+  }, FingerprintE, FingerprintR> | undefined;
+  readonly filterFiles?: ((files: ReadonlyArray<ChangedFile>) => ReadonlyArray<ChangedFile>) | undefined;
+}
+/** Host-derived check conclusion; model verdict prose cannot weaken it. */
+declare const concludeReviewOutcome: (outcome: ReviewRunOutcome) => {
+  readonly conclusion: ReviewCheckConclusion;
+  readonly reasons: ReadonlyArray<string>;
+};
+/**
+ * Harness one already-built reviewer inside the Actions environment: resolve
+ * the target from the event, provide the GitHub source/publisher/prior
+ * reviews, validate/select bounded continuity scope, write step outputs, and apply
+ * the host-derived coverage/blocker gate. Draft and non-PR skips are values;
+ * an unchanged reviewed head preserves and enforces its stored conclusion. The reviewer's
+ * remaining requirements — its model client, any extra tool handlers — stay
+ * visible in `R` for the caller.
+ */
+declare const runReviewAction: <E, R, FingerprintE = never, FingerprintR = never>(reviewer: HarnessedReviewer<E, R, FingerprintE, FingerprintR>, options?: {
+  readonly post?: boolean | undefined;
+  readonly failOn?: FailOnPolicy | undefined;
+  /** Skip model execution when the current head already has complete stored coverage. */
+  readonly skipUnchanged?: boolean | undefined;
+  /** Incremental by default; `final` deliberately re-reviews the full PR diff. */
+  readonly reviewMode?: ReviewMode | undefined;
+  /** Model binding descriptor for the Actions step summary. */
+  readonly modelLabel?: string | undefined;
+  /** Explicit test/custom-host history override; GitHub owns the default adapter. */
+  readonly priorReviews?: PriorReviews["Service"] | undefined;
+}) => Effect.Effect<{
+  _tag: "Skipped";
+  reason: string;
+} | {
+  reason?: undefined;
+  _tag: "Completed";
+  outcome: ReviewRunOutcome;
+}, E | FingerprintE | Config.ConfigError | import("effect/PlatformError").PlatformError | PullRequestSourceFailure | ReviewGateFailed | ReviewTargetUnresolved, FileSystem.FileSystem | ReviewStateAuthenticator | Exclude<FingerprintR, PriorReviews | PullRequestSource | ReviewPublisher> | Exclude<R, PriorReviews | PullRequestSource | ReviewPublisher>>;
+/**
+ * The packaged, environment-driven action program: inputs from PR_REVIEW_*,
+ * reviewer built from the packaged factory, provider client from the
+ * matching credential environment variable.
+ */
+declare const reviewActionProgram: Effect.Effect<{
+  _tag: "Skipped";
+  reason: string;
+} | {
+  reason?: undefined;
+  _tag: "Completed";
+  outcome: ReviewRunOutcome;
+}, import("effect-agent").AgentApprovalDenied | import("effect-agent").AgentApprovalPending | import("effect-agent").AgentChildPending | import("effect-agent").AgentInputError | import("effect-agent").AgentOutputError | import("effect-agent").AgentPolicyError | import("effect/unstable/ai/AiError").AiError | import("effect-agent").BudgetAdapterError | BudgetExceeded | Config.ConfigError | GitHubApiFailure | GuidanceFileUnreadable | InvalidEffortInput | InvalidMaxDurationInput | import("effect-agent").ModelProtocolError | import("effect/PlatformError").PlatformError | PullRequestSourceFailure | ReviewGateFailed | ReviewTargetUnresolved | Schema.SchemaError, FileSystem.FileSystem>;
+/** Run the packaged action program on Node; the bundled action entrypoint. */
+declare const main: () => void;
+/** The packaged GitHub Actions surface. */
+declare const PrReviewAction: {
+  readonly inputs: () => Effect.Effect<{
+    provider: ReviewProvider;
+    model: string | undefined;
+    effort: number | undefined;
+    post: boolean;
+    applyVerdict: boolean;
+    fanOut: boolean;
+    guidance: string | undefined;
+    guidanceFile: string | undefined;
+    ignore: string[];
+    maxFindings: number | undefined;
+    maxDurationMinutes: number | undefined;
+    reviewMode: "final" | "incremental";
+    failOn: "never" | "request-changes";
+    skipUnchanged: boolean;
+  }, Config.ConfigError | InvalidEffortInput | InvalidMaxDurationInput, never>;
+  readonly run: typeof runReviewAction;
+  readonly program: Effect.Effect<{
+    _tag: "Skipped";
+    reason: string;
+  } | {
+    reason?: undefined;
+    _tag: "Completed";
+    outcome: ReviewRunOutcome;
+  }, import("effect-agent").AgentApprovalDenied | import("effect-agent").AgentApprovalPending | import("effect-agent").AgentChildPending | import("effect-agent").AgentInputError | import("effect-agent").AgentOutputError | import("effect-agent").AgentPolicyError | import("effect/unstable/ai/AiError").AiError | import("effect-agent").BudgetAdapterError | BudgetExceeded | Config.ConfigError | GitHubApiFailure | GuidanceFileUnreadable | InvalidEffortInput | InvalidMaxDurationInput | import("effect-agent").ModelProtocolError | import("effect/PlatformError").PlatformError | PullRequestSourceFailure | ReviewGateFailed | ReviewTargetUnresolved | Schema.SchemaError, FileSystem.FileSystem>;
+  readonly main: typeof main;
+};
+//#endregion
+export { FailOnPolicy, GuidanceFileUnreadable, HarnessedReviewer, InvalidMaxDurationInput, MAX_GUIDANCE_FILE_CHARS, PrReviewAction, ResolvedActionInputs, ReviewActionResult, ReviewCheckConclusion, ReviewGateFailed, concludeReviewOutcome, main, resolveActionInputs, resolveGuidance, reviewActionProgram, runReviewAction, writeActionOutputs, writeStepSummary };
+//# sourceMappingURL=action.d.mts.map