1import type {
2 BranchNamingOptions,
3 ChatAttachment,
4 ModelSelection,
5 PullRequestReviewGuide,
6 TextGenerationError,
7} from "@t3tools/contracts";
8import type * as Effect from "effect/Effect";
9
10import type { TextGenerationPolicy } from "./textGenerationPolicy.ts";
11
12export interface CommitMessageGenerationInput {
13 cwd: string;
14 branch: string | null;
15 stagedSummary: string;
16 stagedPatch: string;
17 /** When true, the model also returns a semantic branch name for the change. */
18 includeBranch?: boolean;
19 policy?: TextGenerationPolicy | undefined;
20 /** What model and provider to use for generation. */
21 modelSelection: ModelSelection;
22}
23
24export interface CommitMessageGenerationResult {
25 subject: string;
26 body: string;
27 /** Only present when `includeBranch` was set on the input. */
28 branch?: string | undefined;
29}
30
31export interface PrContentGenerationInput {
32 cwd: string;
33 baseBranch: string;
34 headBranch: string;
35 commitSummary: string;
36 diffSummary: string;
37 diffPatch: string;
38 changeRequestTemplate?: string | undefined;
39 policy?: TextGenerationPolicy | undefined;
40 /** What model and provider to use for generation. */
41 modelSelection: ModelSelection;
42}
43
44export interface PrContentGenerationResult {
45 title: string;
46 body: string;
47}
48
49export interface BranchNameGenerationInput {
50 naming?: BranchNamingOptions | undefined;
51 cwd: string;
52 message: string;
53 attachments?: ReadonlyArray<ChatAttachment> | undefined;
54 /** What model and provider to use for generation. */
55 modelSelection: ModelSelection;
56}
57
58export interface BranchNameGenerationResult {
59 branch: string;
60}
61
62export interface ThreadTitleGenerationInput {
63 linkedContext?: string | undefined;
64 cwd: string;
65 message: string;
66 /** Present when replacing an existing title from the current thread history. */
67 previousTitle?: string | undefined;
68 attachments?: ReadonlyArray<ChatAttachment> | undefined;
69 /** What model and provider to use for generation. */
70 modelSelection: ModelSelection;
71}
72
73export interface ThreadTitleGenerationResult {
74 title: string;
75 needsRefinement?: boolean | undefined;
76}
77
78export interface ReviewGuideStackLayer {
79 readonly number: number;
80 readonly title: string | null;
81 /** The layer's head in the checkout, null where it could not be fetched. */
82 readonly headSha: string | null;
83 readonly state: "open" | "closed" | "merged";
84}
85
86export interface ReviewGuideGenerationInput {
87 /** A disposable checkout of the change's head. The model investigates it read-only. */
88 cwd: string;
89 number: number;
90 title: string;
91 /** The author's own description, which states intent the diff cannot. */
92 description: string;
93 baseBranch: string;
94 /** The commit the change is measured from, present in `cwd`. */
95 baseCommit: string;
96 /**
97 * What review already settled: resolved conversations, reduced to who raised what. The guide
98 * leaves these alone rather than raising them again.
99 */
100 settledReview: string;
101 /** The maintainer's preferences for guides (tone, emphasis, ordering). Empty for none. */
102 instructions?: string | undefined;
103 /**
104 * The stack the change is a layer of, bottom first, when it is in one. Another layer's head is
105 * fetched into `cwd` where the host served it, so the model can read across a seam.
106 */
107 stack?: ReadonlyArray<ReviewGuideStackLayer> | undefined;
108 /** What model and provider to use for generation. */
109 modelSelection: ModelSelection;
110}
111
112/** A guide as the model wrote it, before the server holds it to the change. */
113export type ReviewGuideGenerationResult = Omit<
114 PullRequestReviewGuide,
115 "headSha" | "generatedAt" | "modelSelection"
116>;
117
118/** Commit, change request, branch, and title generation backed by one provider instance. */
119export interface ProviderTextGeneration {
120 /**
121 * Generate a commit message from staged change context.
122 */
123 readonly generateCommitMessage: (
124 input: CommitMessageGenerationInput,
125 ) => Effect.Effect<CommitMessageGenerationResult, TextGenerationError>;
126
127 /**
128 * Generate change request title/body from branch and diff context.
129 */
130 readonly generatePrContent: (
131 input: PrContentGenerationInput,
132 ) => Effect.Effect<PrContentGenerationResult, TextGenerationError>;
133
134 /**
135 * Generate a concise branch name from a user message.
136 */
137 readonly generateBranchName: (
138 input: BranchNameGenerationInput,
139 ) => Effect.Effect<BranchNameGenerationResult, TextGenerationError>;
140
141 /** Generate a concise thread title from a first message or thread history. */
142 readonly generateThreadTitle: (
143 input: ThreadTitleGenerationInput,
144 ) => Effect.Effect<ThreadTitleGenerationResult, TextGenerationError>;
145
146 /** Explain a change request to the maintainer deciding whether it lands. */
147 readonly generateReviewGuide: (
148 input: ReviewGuideGenerationInput,
149 ) => Effect.Effect<ReviewGuideGenerationResult, TextGenerationError>;
150}