Open History to see the last commit
1import type { EnvironmentId, PullRequestRef, PullRequestReviewGuideStop } from "@t3tools/contracts";
2import { ScrollTextIcon, TriangleAlertIcon } from "lucide-react";
3import { useEffect, useEffectEvent } from "react";
4
5import type { ReviewCommentContext } from "~/reviewCommentContext";
6
7import { Alert, AlertAction, AlertDescription } from "../ui/alert";
8import { Button } from "../ui/button";
9import { Spinner } from "../ui/spinner";
10import type { ExcerptCommenting } from "./guide/GuideExcerpt";
11import { GuideProseContext } from "./guide/GuideProse";
12import { GuideTour } from "./guide/GuideTour";
13import { useReviewGuideWriter } from "./guide/useReviewGuideWriter";
14import {
15 nextPendingReviewCommentId,
16 pullRequestReviewKey,
17 usePendingReviewComments,
18 usePullRequestReviewStore,
19} from "./pullRequestReviewStore";
20import type { PullRequestCompletionScope } from "./PullRequestMarkdownTextarea";
21
22export function PullRequestGuideTab({
23 environmentId,
24 reference,
25 title,
26 workspaceRoot,
27 active,
28 canComment,
29 rangeComments,
30 completionScope,
31 onAskAboutLines,
32 onAskAboutStop,
33 onFinishReview,
34 onOpenFile,
35 onTourShown,
36}: {
37 environmentId: EnvironmentId;
38 reference: PullRequestRef;
39 title: string | null;
40 workspaceRoot: string;
41 active: boolean;
42 canComment: boolean;
43 rangeComments: boolean;
44 completionScope: PullRequestCompletionScope | null;
45 onAskAboutLines: ((comment: ReviewCommentContext, request: string) => void) | null;
46 onAskAboutStop:
47 | ((stop: PullRequestReviewGuideStop, index: number, question: string) => void)
48 | null;
49 onFinishReview: (() => void) | null;
50 onOpenFile: (path: string) => void;
51 onTourShown?: (() => void) | undefined;
52}) {
53 const { query, data, running, canWrite, write } = useReviewGuideWriter({
54 environmentId,
55 reference,
56 title,
57 });
58 const reviewKey = pullRequestReviewKey(reference);
59 const pending = usePendingReviewComments(reference);
60 const addComment = usePullRequestReviewStore((store) => store.addComment);
61 const removeComment = usePullRequestReviewStore((store) => store.removeComment);
62 const commenting: ExcerptCommenting | null =
63 !canComment && onAskAboutLines === null
64 ? null
65 : {
66 canComment,
67 rangeComments,
68 completionScope,
69 pending,
70 onComment: ({ path, oldPath, position, startPosition, body }) =>
71 addComment(reviewKey, {
72 id: nextPendingReviewCommentId(),
73 path,
74 ...(oldPath === null ? {} : { oldPath }),
75 ...(startPosition === undefined ? {} : { startPosition }),
76 position,
77 body,
78 }),
79 onRemove: (commentId) => removeComment(reviewKey, commentId),
80 onAskAgent: onAskAboutLines,
81 };
82 const guide = data?.guide ?? null;
83 const tourShown = active && guide !== null;
84 const reportTourShown = useEffectEvent(() => onTourShown?.());
85 // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- tells the parent once the loaded guide tour is on screen, which data arrival can cause
86 useEffect(() => {
87 if (tourShown) reportTourShown();
88 }, [tourShown]);
89 const runState = data?.run ?? null;
90 const currentHeadSha = data?.currentHeadSha ?? null;
91 const stale = guide !== null && currentHeadSha !== null && currentHeadSha !== guide.headSha;
92 const failure =
93 runState?._tag === "Failed" && runState.headSha === currentHeadSha ? runState.detail : null;
94 const writeButton = (label: string, size: "sm" | "xs") =>
95 canWrite ? (
96 <Button size={size} variant="outline" disabled={running} onClick={() => void write()}>
97 {running ? <Spinner /> : <ScrollTextIcon aria-hidden className="size-3.5" />}
98 {running ? "Reading the change..." : label}
99 </Button>
100 ) : null;
101
102 if (guide === null) {
103 if (query.isPending && data === null) {
104 return (
105 <div className="flex min-h-48 items-center justify-center">
106 <Spinner />
107 </div>
108 );
109 }
110 return (
111 <div className="scrollbar-gutter-both flex h-full flex-col items-center justify-center-safe gap-2 overflow-y-auto px-4 py-10 text-center">
112 <p className="text-sm font-medium text-foreground">
113 {running
114 ? "Writing a review guide"
115 : failure === null
116 ? "No review guide yet"
117 : "Could not write a review guide"}
118 </p>
119 <p className="max-w-md text-xs text-muted-foreground">
120 {running
121 ? "An agent is reading the change. A large one takes a few minutes. You can leave; you will be told when it is ready."
122 : failure === null
123 ? (query.error ??
124 "A guide is a tour of the change: stops through the code in reading order, with the calls only a maintainer can make.")
125 : FAILURE_HINT}
126 </p>
127 {writeButton(failure === null ? "Write guide" : "Try again", "sm")}
128 {failure === null || running ? null : <FailureDetails detail={failure} />}
129 </div>
130 );
131 }
132
133 const banner =
134 stale || failure !== null || running ? (
135 <Alert variant={running ? "info" : "warning"}>
136 {running ? <Spinner /> : <TriangleAlertIcon />}
137 <AlertDescription>
138 {running ? (
139 "Rewriting this guide. You will be told when the new one is ready."
140 ) : failure === null ? (
141 "Written before the latest push."
142 ) : (
143 <>
144 {`Could not rewrite this guide. ${FAILURE_HINT}`}
145 <FailureDetails detail={failure} />
146 </>
147 )}
148 </AlertDescription>
149 {!running && canWrite ? <AlertAction>{writeButton("Rewrite", "xs")}</AlertAction> : null}
150 </Alert>
151 ) : null;
152
153 return (
154 <GuideProseContext value={{ environmentId, cwd: workspaceRoot }}>
155 <GuideTour
156 environmentId={environmentId}
157 reference={reference}
158 guide={guide}
159 banner={banner}
160 active={active}
161 commenting={commenting}
162 onAsk={
163 onAskAboutStop === null
164 ? null
165 : (index, question) => {
166 const stop = guide.stops[index];
167 if (stop !== undefined) onAskAboutStop(stop, index, question);
168 }
169 }
170 onFinish={onFinishReview}
171 onOpenFile={onOpenFile}
172 />
173 </GuideProseContext>
174 );
175}
176
177const FAILURE_HINT = "Check the review guide model in Settings → Source control.";
178
179function FailureDetails({ detail }: { detail: string }) {
180 return (
181 <details className="w-full max-w-lg text-xs text-muted-foreground">
182 <summary className="cursor-pointer rounded-sm -outline-offset-2 hover:text-foreground focus-visible:outline-2 focus-visible:outline-ring">
183 Technical details
184 </summary>
185 <pre className="scrollbar-gutter-both mt-2 max-h-40 overflow-auto whitespace-pre-wrap break-words rounded-lg border border-border bg-muted/40 p-3 text-left font-mono text-xs">
186 {detail}
187 </pre>
188 </details>
189 );
190}