@effect-agent/pr-review 0.1.0-beta.36 → 0.1.0-beta.38

package/NOTICE

@@ -0,0 +1,27 @@
+This package includes adaptations of the review instructions and numbered diff
+hunk presentation from PR-Agent:
+
+https://github.com/The-PR-Agent/pr-agent
+Pinned source: 9e6d6a5b40f9ce90bcc085466ba7a42c0837c37a
+
+MIT License
+
+Copyright (c) 2026 The PR Agent
+
+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

@@ -1,17 +1,40 @@
 # @effect-agent/pr-review
 
-A small, provider-neutral review agent.
+A small, provider-neutral review agent. One bounded model run receives every admitted patch as
+numbered new and old hunks, reads immutable base or head source when needed, and returns findings
+through a required native completion Tool. There is no voting, candidate cache, private hypothesis
+handoff, or repository code execution.
 
-The package accepts an already-collected diff, makes one model call with no
-tools, validates the returned paths and line anchors, and returns a structured
-report with cached, uncached, cache-write, and output token usage plus, when
-supplied by the host, an estimated cost. It knows nothing about GitHub,
-webhooks, comments, providers, retries, or review history; those belong to the
-host channel.
-Each finding carries a severity and problem category so a host can render a
-scannable review without another model call.
+The reviewer traces changed entry points and boundaries through downstream consumers, guards,
+finite resources, transformations, effects, completion, and unchanged callees. A finding must have
+a supported trigger, concrete terminal failure, causative changed edge, reachable impact, and a
+cause-level repair checked against both a legitimate boundary input and excluded scope. Incremental
+findings must be introduced, exposed, or materially affected by the exact delta; unrelated old bugs
+and target-only changes remain out of scope, while explicit reverts remain reviewable.
+
+The result contains model findings with host-validated paths and line anchors, exact duplicate
+removal, aggregate usage, and optional host-priced cost. Unknown changed paths fail closed and
+invalid inline anchors become top-level findings. Model output, usage, context, and retained response
+bytes remain bounded. Public finding paths, titles, and bodies retain their 512, 200, and
+2,000-character limits.
+
+The reviewer does not resolve previous findings or declare a partial review safe
+to merge. GitHub history, credentials, diff collection, and publication belong to
+the host channel.
 
 ```ts
 const reviewer = makeReviewer({ model, guidance, estimateCostMicrousd });
-const outcome = yield * reviewer.review(request);
+const program = reviewer.review(request).pipe(Effect.provideService(ReviewRepository, repository));
 ```
+
+`repository.readFile` and `repository.findFiles` return typed Effects. Hosts must
+authorize the source sent to their model, enforce immutable revisions and read
+bounds, and treat source content as untrusted data. The reviewer exposes this
+dependency in its Effect requirements; it has no ambient filesystem or network
+access and does not cache review answers.
+
+`ReviewSource.fromText(request, text)` applies the shared line and character
+bounds after the host authorizes and reads a file.
+
+The numbered hunk presentation and portions of the review instructions are adapted from
+[PR-Agent](https://github.com/The-PR-Agent/pr-agent). See `NOTICE` for its MIT license attribution.

package/dist/index.d.mts

@@ -1,6 +1,49 @@
-import { Effect, Schema } from "effect";
-import { AgentPolicy, IdGenerator, RunCostEstimator, UsageBudgetLimits } from "effect-agent";
-import { LanguageModel, Model, Toolkit } from "effect/unstable/ai";
+import { Context, Effect, Schema } from "effect";
+import { IdGenerator, RunCostEstimator } from "effect-agent";
+import { LanguageModel, Model, Tool, Toolkit } from "effect/unstable/ai";
+//#region src/repository.d.ts
+declare const ReadFileInput: Schema.Struct<{
+  readonly path: Schema.NonEmptyString;
+  readonly revision: Schema.Literals<readonly ["base", "head"]>;
+  readonly startLine: Schema.Int;
+  readonly lineCount: Schema.Int;
+}>;
+declare const ReviewContextError_base: Schema.Class<ReviewContextError, Schema.TaggedStruct<"ReviewContextError", {
+  readonly message: Schema.NonEmptyString;
+}>, import("effect/Cause").YieldableError>;
+declare class ReviewContextError extends ReviewContextError_base {}
+declare const ReviewSource_base: Schema.Class<ReviewSource, Schema.Struct<{
+  readonly path: Schema.NonEmptyString;
+  readonly revision: Schema.Literals<readonly ["base", "head"]>;
+  readonly startLine: Schema.Int;
+  readonly totalLines: Schema.Natural;
+  readonly content: Schema.String;
+}>, {}>;
+declare class ReviewSource extends ReviewSource_base {
+  /** Apply the same line and character bounds in live and frozen-source adapters. */
+  static readonly fromText: (input: {
+    readonly path: string;
+    readonly revision: "base" | "head";
+    readonly startLine: number;
+    readonly lineCount: number;
+  }, text: string) => Effect.Effect<ReviewSource, ReviewContextError, never>;
+}
+declare const ReviewFileList_base: Schema.Class<ReviewFileList, Schema.Struct<{
+  readonly paths: Schema.$Array<Schema.NonEmptyString>;
+  readonly truncated: Schema.Boolean;
+}>, {}>;
+declare class ReviewFileList extends ReviewFileList_base {}
+declare const FindFilesInput: Schema.Struct<{
+  readonly query: Schema.String;
+  readonly revision: Schema.Literals<readonly ["base", "head"]>;
+}>;
+declare const ReviewRepository_base: Context.ServiceClass<ReviewRepository, "@effect-agent/pr-review/ReviewRepository", {
+  readonly readFile: (input: typeof ReadFileInput.Type) => Effect.Effect<ReviewSource, ReviewContextError>;
+  readonly findFiles: (input: typeof FindFilesInput.Type) => Effect.Effect<ReviewFileList, ReviewContextError>;
+}>;
+/** Read-only source access bound by the host to the request's exact two revisions. */
+declare class ReviewRepository extends ReviewRepository_base {}
+//#endregion
 //#region src/review.d.ts
 declare const ReviewChange_base: Schema.Class<ReviewChange, Schema.Struct<{
   readonly path: Schema.NonEmptyString;
@@ -13,6 +56,7 @@ declare const ReviewRequest_base: Schema.Class<ReviewRequest, Schema.Struct<{
   readonly description: Schema.String;
   readonly baseRevision: Schema.NonEmptyString;
   readonly headRevision: Schema.NonEmptyString;
+  readonly scope: Schema.optionalKey<Schema.Literals<readonly ["full", "incremental"]>>;
   readonly changes: Schema.$Array<typeof ReviewChange>;
   readonly unreviewedPaths: Schema.$Array<Schema.NonEmptyString>;
 }>, {}>;
@@ -21,14 +65,14 @@ declare class ReviewRequest extends ReviewRequest_base {}
 declare const ReviewSeverity: Schema.Literals<readonly ["blocking", "important", "nit"]>;
 type ReviewSeverity = typeof ReviewSeverity.Type;
 /** A model-claimed problem kind used only to label findings for readers. */
-declare const ReviewCategory: Schema.Literals<readonly ["correctness", "security", "concurrency", "performance", "resources", "reliability", "error-handling", "testing", "maintainability", "style", "docs"]>;
+declare const ReviewCategory: Schema.Literals<readonly ["correctness", "security", "concurrency", "performance", "resources", "reliability", "error-handling", "testing", "maintainability", "docs"]>;
 type ReviewCategory = typeof ReviewCategory.Type;
 declare const ReviewFinding_base: Schema.Class<ReviewFinding, Schema.Struct<{
   readonly path: Schema.NonEmptyString;
   readonly line: Schema.optionalKey<Schema.Int>;
   readonly severity: Schema.Literals<readonly ["blocking", "important", "nit"]>;
   /** Presentation label only; it never changes review admission or failure policy. */
-  readonly category: Schema.Literals<readonly ["correctness", "security", "concurrency", "performance", "resources", "reliability", "error-handling", "testing", "maintainability", "style", "docs"]>;
+  readonly category: Schema.Literals<readonly ["correctness", "security", "concurrency", "performance", "resources", "reliability", "error-handling", "testing", "maintainability", "docs"]>;
   readonly title: Schema.NonEmptyString;
   readonly body: Schema.NonEmptyString;
 }>, {}>;
@@ -38,7 +82,7 @@ declare const ReviewReport_base: Schema.Class<ReviewReport, Schema.Struct<{
   readonly summary: Schema.NonEmptyString;
   readonly findings: Schema.$Array<typeof ReviewFinding>;
 }>, {}>;
-/** The only model-authored output. An empty findings array is a successful review. */
+/** Host-validated findings with a host-authored summary of the reviewed scope. */
 declare class ReviewReport extends ReviewReport_base {}
 declare const ReviewUsage_base: Schema.Class<ReviewUsage, Schema.Struct<{
   readonly inputTokens: Schema.Natural;
@@ -55,48 +99,92 @@ declare const ReviewOutcome_base: Schema.Class<ReviewOutcome, Schema.Struct<{
   readonly usage: typeof ReviewUsage;
 }>, {}>;
 declare class ReviewOutcome extends ReviewOutcome_base {}
-declare const reviewPolicy: AgentPolicy;
-declare const reviewBudgetLimits: UsageBudgetLimits;
-/** Return every RIGHT-side line on which GitHub can place a diff comment. */
-declare const commentableLines: (patch: string) => ReadonlySet<number>;
+declare const ReviewSubmission_base: Schema.Class<ReviewSubmission, Schema.Struct<{
+  readonly findings: Schema.$Array<Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly line: Schema.optionalKey<Schema.Int>;
+    readonly category: Schema.Literals<readonly ["correctness", "security", "concurrency", "performance", "resources", "reliability", "error-handling", "testing", "maintainability", "docs"]>;
+    readonly title: Schema.NonEmptyString;
+    readonly body: Schema.NonEmptyString;
+    readonly priority: Schema.Literals<readonly [0, 1, 2, 3]>;
+  }>>;
+}>, {}>;
+declare class ReviewSubmission extends ReviewSubmission_base {}
+declare const FormattedReviewRequest_base: Schema.Class<FormattedReviewRequest, Schema.Struct<{
+  readonly title: Schema.String;
+  readonly description: Schema.String;
+  readonly baseRevision: Schema.NonEmptyString;
+  readonly headRevision: Schema.NonEmptyString;
+  readonly scope: Schema.optionalKey<Schema.Literals<readonly ["full", "incremental"]>>;
+  readonly unreviewedPaths: Schema.$Array<Schema.NonEmptyString>;
+  readonly changes: Schema.$Array<Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly formattedDiff: Schema.NonEmptyString;
+  }>>;
+}>, {}>;
+declare class FormattedReviewRequest extends FormattedReviewRequest_base {}
+declare const ReviewVerificationError_base: Schema.Class<ReviewVerificationError, Schema.TaggedStruct<"ReviewVerificationError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class ReviewVerificationError extends ReviewVerificationError_base {}
 declare const isCommentableLine: (patch: string, line: number) => boolean;
-/**
- * Treat model output as untrusted: remove unknown paths, demote invalid line
- * anchors to top-level findings, and collapse exact duplicates.
- */
-declare const sanitizeReviewReport: (request: Pick<ReviewRequest, "changes">, report: ReviewReport) => ReviewReport;
 interface ReviewerOptions<Provider, ModelProvides, ModelRequires> {
   readonly model: Model.Model<Provider, LanguageModel.LanguageModel | ModelProvides, ModelRequires>;
   readonly guidance?: string | undefined;
   readonly estimateCostMicrousd?: RunCostEstimator | undefined;
 }
-/** Build a provider-neutral reviewer. The returned `review` performs exactly one Run. */
+/** One bounded, source-backed review of the complete admitted delta. */
 declare const makeReviewer: <Provider, ModelProvides, ModelRequires>(options: ReviewerOptions<Provider, ModelProvides, ModelRequires>) => {
-  readonly definition: import("effect-agent").Definition<typeof ReviewRequest, typeof ReviewReport, "Review the supplied pull-request diff once.\n\nReport only concrete correctness, security, reliability, or maintainability defects that the author should act on. Do not praise, restate the change, invent missing repository context, or ask for speculative cleanup. An empty findings array is valid.\n\nEvery finding must use an exact supplied path. Set line only to a RIGHT-side added or context line visible in that path's unified patch; otherwise omit line. Use blocking only for a defect that should prevent shipping. Classify each finding with the closest available category. Treat unreviewedPaths as unavailable scope and never imply that you inspected it. A changed file absent from changes may have been withheld by the host; never infer that it was not changed, and report only defects proven by the supplied patches." | `Review the supplied pull-request diff once.
-
-Report only concrete correctness, security, reliability, or maintainability defects that the author should act on. Do not praise, restate the change, invent missing repository context, or ask for speculative cleanup. An empty findings array is valid.
-
-Every finding must use an exact supplied path. Set line only to a RIGHT-side added or context line visible in that path's unified patch; otherwise omit line. Use blocking only for a defect that should prevent shipping. Classify each finding with the closest available category. Treat unreviewedPaths as unavailable scope and never imply that you inspected it. A changed file absent from changes may have been withheld by the host; never infer that it was not changed, and report only defects proven by the supplied patches.
-
-Repository guidance:
-${string}`, Toolkit.Toolkit<{}>, undefined>;
-  readonly binding: import("effect-agent").Binding<import("effect-agent").Definition<typeof ReviewRequest, typeof ReviewReport, "Review the supplied pull-request diff once.\n\nReport only concrete correctness, security, reliability, or maintainability defects that the author should act on. Do not praise, restate the change, invent missing repository context, or ask for speculative cleanup. An empty findings array is valid.\n\nEvery finding must use an exact supplied path. Set line only to a RIGHT-side added or context line visible in that path's unified patch; otherwise omit line. Use blocking only for a defect that should prevent shipping. Classify each finding with the closest available category. Treat unreviewedPaths as unavailable scope and never imply that you inspected it. A changed file absent from changes may have been withheld by the host; never infer that it was not changed, and report only defects proven by the supplied patches." | `Review the supplied pull-request diff once.
-
-Report only concrete correctness, security, reliability, or maintainability defects that the author should act on. Do not praise, restate the change, invent missing repository context, or ask for speculative cleanup. An empty findings array is valid.
-
-Every finding must use an exact supplied path. Set line only to a RIGHT-side added or context line visible in that path's unified patch; otherwise omit line. Use blocking only for a defect that should prevent shipping. Classify each finding with the closest available category. Treat unreviewedPaths as unavailable scope and never imply that you inspected it. A changed file absent from changes may have been withheld by the host; never infer that it was not changed, and report only defects proven by the supplied patches.
-
-Repository guidance:
-${string}`, Toolkit.Toolkit<{}>, undefined>, Model.Model<Provider, ModelProvides | LanguageModel.LanguageModel, ModelRequires>>;
-  readonly review: (request: ReviewRequest) => Effect.Effect<ReviewOutcome, import("effect-agent").AgentRuntimeFailure<import("effect-agent").RuntimeBinding<typeof ReviewRequest, typeof ReviewReport, "Review the supplied pull-request diff once.\n\nReport only concrete correctness, security, reliability, or maintainability defects that the author should act on. Do not praise, restate the change, invent missing repository context, or ask for speculative cleanup. An empty findings array is valid.\n\nEvery finding must use an exact supplied path. Set line only to a RIGHT-side added or context line visible in that path's unified patch; otherwise omit line. Use blocking only for a defect that should prevent shipping. Classify each finding with the closest available category. Treat unreviewedPaths as unavailable scope and never imply that you inspected it. A changed file absent from changes may have been withheld by the host; never infer that it was not changed, and report only defects proven by the supplied patches." | `Review the supplied pull-request diff once.
-
-Report only concrete correctness, security, reliability, or maintainability defects that the author should act on. Do not praise, restate the change, invent missing repository context, or ask for speculative cleanup. An empty findings array is valid.
-
-Every finding must use an exact supplied path. Set line only to a RIGHT-side added or context line visible in that path's unified patch; otherwise omit line. Use blocking only for a defect that should prevent shipping. Classify each finding with the closest available category. Treat unreviewedPaths as unavailable scope and never imply that you inspected it. A changed file absent from changes may have been withheld by the host; never infer that it was not changed, and report only defects proven by the supplied patches.
-
-Repository guidance:
-${string}`, {}, Provider, ModelProvides, ModelRequires, never, never, undefined>, import("effect-agent").BudgetAdapterError | import("effect-agent").BudgetExceeded, never>, Exclude<Exclude<Exclude<ModelRequires, import("effect-agent").EngineProvidedToolServices>, IdGenerator>, import("effect/Scope").Scope>>;
+  readonly review: (request: ReviewRequest) => Effect.Effect<ReviewOutcome, ReviewVerificationError | import("effect-agent").AgentRuntimeFailure<import("effect-agent").RuntimeBinding<typeof FormattedReviewRequest, typeof ReviewSubmission, string, {
+    readonly find_files: Tool.Tool<"find_files", {
+      readonly parameters: Schema.Struct<{
+        readonly query: Schema.String;
+        readonly revision: Schema.Literals<readonly ["base", "head"]>;
+      }>;
+      readonly success: typeof ReviewFileList;
+      readonly failure: typeof ReviewContextError;
+      readonly failureMode: "return";
+    }, never>;
+    readonly read_file: Tool.Tool<"read_file", {
+      readonly parameters: Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly revision: Schema.Literals<readonly ["base", "head"]>;
+        readonly startLine: Schema.Int;
+        readonly lineCount: Schema.Int;
+      }>;
+      readonly success: typeof ReviewSource;
+      readonly failure: typeof ReviewContextError;
+      readonly failureMode: "return";
+    }, never>;
+    readonly submit_review: Tool.Tool<"submit_review", {
+      readonly parameters: typeof ReviewSubmission;
+      readonly success: Schema.Null;
+      readonly failure: Schema.Never;
+      readonly failureMode: "error";
+    }, never>;
+  }, Provider, ModelProvides, ModelRequires, never, never, undefined>, import("effect-agent").BudgetAdapterError | import("effect-agent").BudgetExceeded, never>, ReviewRepository | Exclude<Exclude<Exclude<ModelRequires, import("effect-agent").EngineProvidedToolServices>, Tool.Handler<"submit_review"> | IdGenerator | Tool.HandlersFor<{
+    readonly find_files: Tool.Tool<"find_files", {
+      readonly parameters: Schema.Struct<{
+        readonly query: Schema.String;
+        readonly revision: Schema.Literals<readonly ["base", "head"]>;
+      }>;
+      readonly success: typeof ReviewFileList;
+      readonly failure: typeof ReviewContextError;
+      readonly failureMode: "return";
+    }, never>;
+    readonly read_file: Tool.Tool<"read_file", {
+      readonly parameters: Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly revision: Schema.Literals<readonly ["base", "head"]>;
+        readonly startLine: Schema.Int;
+        readonly lineCount: Schema.Int;
+      }>;
+      readonly success: typeof ReviewSource;
+      readonly failure: typeof ReviewContextError;
+      readonly failureMode: "return";
+    }, never>;
+  }>>, import("effect/Scope").Scope>>;
 };
 //#endregion
-export { ReviewCategory, ReviewChange, ReviewFinding, ReviewOutcome, ReviewReport, ReviewRequest, ReviewSeverity, ReviewUsage, ReviewerOptions, type RunCostEstimator, commentableLines, isCommentableLine, makeReviewer, reviewBudgetLimits, reviewPolicy, sanitizeReviewReport };
+export { ReviewCategory, ReviewChange, ReviewContextError, ReviewFileList, ReviewFinding, ReviewOutcome, ReviewReport, ReviewRepository, ReviewRequest, ReviewSeverity, ReviewSource, ReviewUsage, ReviewVerificationError, ReviewerOptions, type RunCostEstimator, isCommentableLine, makeReviewer };
 //# sourceMappingURL=index.d.mts.map