Skip to content

Commit 5cf6afd

Browse files
Sophpeyton-altclaude
committed
fix(source-control-entire): show and edit a change's description on its project trail
A change's description is a copy taken when its branch was linked, while entire.com shows and edits the project trail's. An edit from T3 Code rewrote the copy, so the trail's description never changed and T3 Code showed text entire.com no longer did. The detail now reads the project trail's description and shows it under the trail link. The project trail is served by its project's processing cell, which a repository mirrored elsewhere need not share, so the request goes to the cell the change's parent reference names, looked up in `entire cluster list` by slug and jurisdiction, as the CLI does. An unreadable project trail falls back to the change's copy. A description edit is written to the project trail, conditional on the ETag just read, and a 409 or 412 asks for a refresh. Entire no longer accepts description writes on a repository's trail, so when the project trail can't be reached the edit is refused: T3 Code says to try again or edit it on entire.com, and leaves the title as it was. Titles still rename the change, so the list and the detail agree. Co-Authored-By: Peyton Montei <[email protected]> Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent f79f47d commit 5cf6afd

7 files changed

Lines changed: 299 additions & 64 deletions

File tree

‎docs/user/source-control.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,8 @@ A project whose remote is an `entire://` clone URL is an Entire repository; one
132132
repositories; T3 Code lists and reviews its change in your repository, and links to a change on
133133
entire.com open it in T3 Code. Diffs are read from your checkout, fetching the change from the
134134
`entire://` remote without moving your branches. A line comment is an Entire finding, and the
135-
repository's gates show as `Entire:` checks. Descriptions with formatting Entire can't keep, such
135+
repository's gates show as `Entire:` checks. A change shows its trail's description, and editing it
136+
edits the trail's. Descriptions with formatting Entire can't keep, such
136137
as strikethrough or nested lists, are edited on entire.com. Create repositories with
137138
`entire repo create`.
138139

‎packages/source-control-entire/src/server/EntireApi.ts‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,11 @@ export interface EntireApiRequest {
4545
readonly method?: "GET" | "POST" | "PATCH" | "PUT";
4646
readonly path: string;
4747
readonly scope?: "repository" | "project" | "collection";
48+
/**
49+
* Sends the request to this processing cell instead of the repository's: a project trail is
50+
* served by its project's cell, which a repository mirrored elsewhere does not share.
51+
*/
52+
readonly cell?: { readonly slug: string; readonly jurisdiction: string };
4853
readonly headers?: Readonly<Record<string, string>>;
4954
readonly body?: unknown;
5055
}
@@ -172,18 +177,44 @@ export const make = Effect.gen(function* () {
172177
return { repository, coordinates };
173178
});
174179

180+
// Matched on slug and jurisdiction both, as the CLI does: a cell is never guessed.
181+
const cellApiUrl = Effect.fn("EntireApi.cellApiUrl")(function* (
182+
cell: NonNullable<EntireApiRequest["cell"]>,
183+
fail: ReturnType<typeof failure>,
184+
) {
185+
const cells = yield* cli.cells.pipe(
186+
Effect.mapError((cause) =>
187+
fail({ status: null, reason: cliFailure(cause), detail: cause.message, cause }),
188+
),
189+
);
190+
const match = cells.find(
191+
(candidate) =>
192+
candidate.slug === cell.slug &&
193+
candidate.jurisdiction.toLowerCase() === cell.jurisdiction.toLowerCase(),
194+
);
195+
if (match === undefined)
196+
return yield* fail({
197+
status: null,
198+
reason: "failed",
199+
detail: `Entire's cell list has no ${cell.slug} in ${cell.jurisdiction}.`,
200+
});
201+
return match.apiUrl;
202+
});
203+
175204
const requestJson = Effect.fn("EntireApi.requestJson")(function* <S extends JsonSchema>(
176205
input: EntireApiRequest,
177206
schema: S,
178207
) {
179208
const fail = failure(input.operation);
180209
const { repository, coordinates } = yield* locate(input);
181-
const origin = entireApiOrigin(coordinates.apiUrl);
210+
const apiUrl =
211+
input.cell === undefined ? coordinates.apiUrl : yield* cellApiUrl(input.cell, fail);
212+
const origin = entireApiOrigin(apiUrl);
182213
if (origin === null)
183214
return yield* fail({
184215
status: null,
185216
reason: "failed",
186-
detail: `The Entire CLI named ${coordinates.apiUrl} as the API, which is not an Entire API host.`,
217+
detail: `The Entire CLI named ${apiUrl} as the API, which is not an Entire API host.`,
187218
});
188219
yield* Effect.annotateCurrentSpan({
189220
"entire.operation": input.operation,

‎packages/source-control-entire/src/server/EntireCli.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,13 @@ export interface EntireRepositoryCoordinates {
6060
readonly cluster: string | null;
6161
}
6262

63+
/** One of Entire's processing cells, as `entire cluster list` names it. */
64+
export interface EntireCell {
65+
readonly slug: string;
66+
readonly jurisdiction: string;
67+
readonly apiUrl: string;
68+
}
69+
6370
export class EntireCli extends Context.Service<
6471
EntireCli,
6572
{
@@ -69,9 +76,19 @@ export class EntireCli extends Context.Service<
6976
readonly token: Effect.Effect<Redacted.Redacted<string>, EntireCliError>;
7077
readonly invalidateToken: Effect.Effect<void>;
7178
readonly viewer: Effect.Effect<string, EntireCliError>;
79+
/** Where a project trail is served: its project's processing cell, not a repository's. */
80+
readonly cells: Effect.Effect<ReadonlyArray<EntireCell>, EntireCliError>;
7281
}
7382
>()("@t3tools/source-control-entire/server/EntireCli") {}
7483

84+
const decodeClusterList = Schema.decodeUnknownOption(
85+
Schema.fromJsonString(
86+
Schema.Array(
87+
Schema.Struct({ slug: Schema.String, jurisdiction: Schema.String, apiUrl: Schema.String }),
88+
),
89+
),
90+
);
91+
7592
const decodeRepositoryView = Schema.decodeUnknownOption(
7693
Schema.fromJsonString(
7794
Schema.Struct({
@@ -197,6 +214,19 @@ export const make = Effect.gen(function* () {
197214
return login;
198215
});
199216

217+
const lookupCells = Effect.fn("EntireCli.cells")(function* () {
218+
const output = yield* run("EntireCli.cells", ["cluster", "list", "--json"]);
219+
const cells = output.exitCode === 0 ? decodeClusterList(output.stdout.trim()) : Option.none();
220+
if (Option.isNone(cells))
221+
return yield* new EntireCliFailedError({
222+
operation: "list Entire's cells",
223+
detail:
224+
boundedDetail(Option.getOrUndefined(firstNonEmptyLine(output.stderr))) ??
225+
`\`entire cluster list\` exited ${output.exitCode}.`,
226+
});
227+
return cells.value;
228+
});
229+
200230
const repositories = yield* Cache.makeWith(lookupRepository, {
201231
capacity: 64,
202232
timeToLive: (exit) => (Exit.isSuccess(exit) ? REPOSITORY_TTL : Duration.zero),
@@ -211,6 +241,10 @@ export const make = Effect.gen(function* () {
211241
: MISSING_TTL;
212242
const tokens = yield* Cache.makeWith(lookupToken, { capacity: 1, timeToLive: signedInTtl });
213243
const viewers = yield* Cache.makeWith(lookupViewer, { capacity: 1, timeToLive: signedInTtl });
244+
const cells = yield* Cache.makeWith(lookupCells, {
245+
capacity: 1,
246+
timeToLive: (exit) => (Exit.isSuccess(exit) ? REPOSITORY_TTL : Duration.zero),
247+
});
214248

215249
return EntireCli.of({
216250
repository: (reference) => Cache.get(repositories, reference),
@@ -220,6 +254,7 @@ export const make = Effect.gen(function* () {
220254
Cache.invalidate(viewers, "viewer"),
221255
),
222256
viewer: Cache.get(viewers, "viewer"),
257+
cells: Cache.get(cells, "cells"),
223258
});
224259
});
225260

‎packages/source-control-entire/src/server/EntirePullRequestProvider.test.ts‎

Lines changed: 101 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,13 @@ import * as TestClock from "effect/testing/TestClock";
66

77
import * as EntirePullRequestProvider from "./EntirePullRequestProvider.ts";
88
import * as Fixtures from "./entireFixtures.ts";
9-
import { Answer, fakeEntire, TRAIL_COLLECTION } from "./entireTestServer.ts";
9+
import {
10+
Answer,
11+
fakeEntire,
12+
PROJECT_CELL_ORIGIN,
13+
PROJECT_TRAILS,
14+
TRAIL_COLLECTION,
15+
} from "./entireTestServer.ts";
1016

1117
const target = { cwd: "/repo", host: "entire.io", repository: "gh/acme/web", number: 7 };
1218

@@ -150,71 +156,129 @@ describe("EntirePullRequestProvider", () => {
150156
},
151157
);
152158

153-
it.effect("renames a trail, and rewrites its description against the version read", () => {
154-
const parent = { number: 1070, url: "https://entire.com/et/acme/-/trails/1070" };
155-
const reads: Array<unknown> = [
156-
{ ...Fixtures.detail, parent, body_document: { text_snapshot: "Old", etag: 'W/"d1"' } },
157-
// No document yet: there is no version to name.
158-
{ ...Fixtures.detail, body_document: { text_snapshot: "", etag: "" } },
159-
];
159+
it.effect("renames a trail, and refuses a description it can't route to a project trail", () => {
160160
const server = fakeEntire({
161161
"PATCH /trails/7": { trail: {} },
162-
"GET /trails/7": () => reads.shift(),
163-
"PUT /trails/7/body": { etag: 'W/"d2"' },
162+
"GET /trails/7": {
163+
...Fixtures.detail,
164+
body_document: { text_snapshot: "Old", etag: 'W/"d1"' },
165+
},
164166
});
165167
return Effect.gen(function* () {
166168
const provider = yield* EntirePullRequestProvider.make;
167169
yield* provider.updateChangeRequest!({ ...target, title: "Add the other thing" });
168-
yield* provider.updateChangeRequest!({
170+
const error = yield* provider.updateChangeRequest!({
169171
...target,
170-
body: `Part of trail [#1070](${parent.url}) on Entire.\n\nNew`,
171-
});
172-
yield* provider.updateChangeRequest!({ ...target, body: "First" });
173-
const writes = server.sent.filter((request) => request.method !== "GET");
172+
title: "Renamed",
173+
body: "New",
174+
}).pipe(Effect.flip);
175+
assert.strictEqual(
176+
error.detail,
177+
"T3 Code couldn't reach this change's project trail to save the description. Try again, or edit it on entire.com.",
178+
);
179+
// Neither the description nor the title was written.
174180
assert.deepStrictEqual(
175-
writes.map((request) => [
176-
`${request.method} ${request.path}`,
177-
request.body,
178-
request.headers["if-match"],
179-
]),
180-
[
181-
["PATCH /trails/7", { title: "Add the other thing" }, undefined],
182-
["PUT /trails/7/body", { markdown: "New", overwrite: false }, 'W/"d1"'],
183-
["PUT /trails/7/body", { markdown: "First", overwrite: false }, undefined],
184-
],
181+
server.sent
182+
.filter((request) => request.method !== "GET")
183+
.map((request) => [`${request.method} ${request.path}`, request.body]),
184+
[["PATCH /trails/7", { title: "Add the other thing" }]],
185185
);
186186
}).pipe(Effect.provide(server.layer));
187187
});
188188

189-
it.effect.each([412, 409])(
190-
"asks for a refresh when the description changed elsewhere (%s)",
191-
(status) => {
189+
describe("a change's project trail", () => {
190+
const trailPath = `${PROJECT_TRAILS}/01J0PARENT0000000000000000`;
191+
const parent = {
192+
number: 1070,
193+
url: "https://entire.com/gh/acme/-/trails/1070",
194+
path: trailPath,
195+
primary_processing_cell: "aws-eu-central-1",
196+
jurisdiction: "eu",
197+
};
198+
const link = `Part of trail [#1070](${parent.url}) on Entire.`;
199+
const change = {
200+
...Fixtures.detail,
201+
parent,
202+
body_document: { text_snapshot: "The copy taken at linking", etag: 'W/"c1"' },
203+
};
204+
205+
it.effect("shows the project trail's description, read from its project's cell", () => {
192206
const server = fakeEntire({
193-
"GET /trails/7": Fixtures.detail,
194-
"PUT /trails/7/body": new Answer(status, { detail: "If-Match does not match" }),
195-
"PATCH /trails/7": { trail: {} },
207+
"GET /trails/7": change,
208+
[`GET ${trailPath}`]: { bodyDocument: { text_snapshot: "The intent, as edited" } },
196209
});
210+
return Effect.gen(function* () {
211+
const provider = yield* EntirePullRequestProvider.make;
212+
const detail = yield* provider.getChangeRequest(target);
213+
assert.strictEqual(detail.body, `${link}\n\nThe intent, as edited`);
214+
assert.strictEqual(
215+
server.sent.find((request) => request.path === trailPath)?.origin,
216+
PROJECT_CELL_ORIGIN,
217+
);
218+
}).pipe(Effect.provide(server.layer));
219+
});
220+
221+
it.effect("falls back to the change's copy when the project trail can't be read", () => {
222+
const server = fakeEntire({ "GET /trails/7": change });
223+
return Effect.gen(function* () {
224+
const provider = yield* EntirePullRequestProvider.make;
225+
const detail = yield* provider.getChangeRequest(target);
226+
assert.strictEqual(detail.body, `${link}\n\nThe copy taken at linking`);
227+
}).pipe(Effect.provide(server.layer));
228+
});
229+
230+
it.effect("saves a description edit to the project trail, against the version read", () => {
231+
const server = fakeEntire(
232+
{
233+
"GET /trails/7": change,
234+
[`GET ${trailPath}`]: { bodyDocument: { text_snapshot: "Old intent" } },
235+
[`PATCH ${trailPath}`]: {},
236+
},
237+
{ etag: 'W/"p1"' },
238+
);
239+
return Effect.gen(function* () {
240+
const provider = yield* EntirePullRequestProvider.make;
241+
yield* provider.updateChangeRequest!({ ...target, body: `${link}\n\nNew intent` });
242+
assert.deepStrictEqual(server.writes(), [`PATCH ${trailPath}`]);
243+
const write = server.sent.at(-1);
244+
assert.deepStrictEqual(write?.body, { body: "New intent" });
245+
assert.strictEqual(write?.headers["if-match"], 'W/"p1"');
246+
assert.strictEqual(write?.origin, PROJECT_CELL_ORIGIN);
247+
}).pipe(Effect.provide(server.layer));
248+
});
249+
250+
it.effect("asks for a refresh when the project trail changed since it was read", () => {
251+
const server = fakeEntire(
252+
{
253+
"GET /trails/7": change,
254+
[`GET ${trailPath}`]: { bodyDocument: { text_snapshot: "Old intent" } },
255+
[`PATCH ${trailPath}`]: new Answer(412, { title: "Precondition Failed" }),
256+
},
257+
{ etag: 'W/"p1"' },
258+
);
197259
return Effect.gen(function* () {
198260
const provider = yield* EntirePullRequestProvider.make;
199261
const error = yield* provider.updateChangeRequest!({
200262
...target,
201263
title: "Renamed",
202-
body: "Mine",
264+
body: "New intent",
203265
}).pipe(Effect.flip);
204-
assert.include(error.detail, "changed elsewhere");
266+
assert.strictEqual(
267+
error.detail,
268+
"The description changed elsewhere. Refresh and try again.",
269+
);
205270
// The title is left as it was.
206-
assert.deepStrictEqual(server.writes(), ["PUT /trails/7/body"]);
271+
assert.deepStrictEqual(server.writes(), [`PATCH ${trailPath}`]);
207272
}).pipe(Effect.provide(server.layer));
208-
},
209-
);
273+
});
274+
});
210275

211276
it.effect("refuses to rewrite formatting Entire's markdown would lose, title and all", () => {
212277
const server = fakeEntire({
213278
"GET /trails/7": {
214279
...Fixtures.detail,
215280
body_document: { text_snapshot: "Plain", etag: 'W/"d1"' },
216281
},
217-
"PUT /trails/7/body": { etag: 'W/"d2"' },
218282
});
219283
return Effect.gen(function* () {
220284
const provider = yield* EntirePullRequestProvider.make;

0 commit comments

Comments
 (0)