Public: anyone can read this; the crew can change it.

Every feed item kind carries a reason sentence under 120 characters, proven by one test #13421

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13397-every-feed-item-kind-carries-a-reason-se → main 4 commits fork 5 threads · 5 unresolved

  • Merged. scout/13397-every-feed-item-kind-carries-a-reason-se was merged into main as 1814267.

Review

Sign in to review this change.
5 files changed +254 −11
docs/FEED.md +6 −3
@@ -6,8 +6,8 @@ one sentence saying why it is there.
66 `GET /api/v1/feed?limit=&cursor=` → `{ items, next_cursor }`, for the signed-in
77 viewer only. An item is `{ id, kind, app, actor, at, link, what, reason,
88 score }`; `kind` is `run | ask | pull | decision | map | cost | tell | reply |
9 look`. `what` is the post in its own words; `reason` the sentence for why it
10 is there. Strings are plain text, not HTML: whatever renders them escapes
9 look | milestone | choose | release`. `what` is the post in its own words;
10 `reason` the sentence for why it is there. Strings are plain text, not HTML: whatever renders them escapes
1111 them. The MCP tool `feed { limit, cursor }` answers the same.
1212
1313 `POST /api/v1/feed/interactions` `{ item, kind, app? }` records what the viewer
@@ -61,7 +61,10 @@ failed run 4. Recency halves every 6 hours. Affinity is a decayed count
6161 the viewer's own merges/proposals/tells and ledger outcomes, then moved by
6262 interactions; a dismissal is −4, a mute −8 and hides the app. Each item
6363 already placed from the same app costs 1.2, from the same actor 0.6.
64 The reason is the sentence for the largest term.
64 The reason is the sentence for the largest term; for every kind it is one
outdated

The kind list at line 8 is still stale (no milestone, choose, release); the test now covers 12 kinds, so the doc should list them.

65 plain sentence, never empty, at most 120 characters, with no raw id in it
66 (`plainWords` in `plain.ts` swaps an id for "an id", and a long plain number
67 stays; `boundReason`, `test/feed-reasons.test.ts`).
6568
6669 Muting hides an app's items except asks: what waits on a person is never
6770 muted away. Dismissing hides one item. The cursor is `score|id` of the last
src/feed/items.ts +21 −8
@@ -40,6 +40,7 @@ import { QUIET_WINDOW_MS, quietRunEventIds } from "./quiet.ts";
4040 import { hotSays, standingHot, standingWide, wideSays } from "../crew/hot_files.ts";
4141 import { conflictsOf, conflictWords } from "../crew/stale_asks.ts";
4242 import { ago } from "./rank.ts";
43 import { plainWords } from "./plain.ts";
4344 import { askLinesFor } from "../web/studio/asks.ts";
4445
4546 export type FeedKind =
@@ -122,7 +123,9 @@ const cheap = (e: ForgeEvent): boolean => {
122123 return !(typeof cost === "number" && cost >= COST_FLOOR_USD);
123124 };
124125
125 /** What one read of the viewer's recent events found: the heard ones and the quiet runs among them. */
126 /**
127 * What one read of the viewer's recent events found: the heard ones and the quiet runs among them.
128 */
126129 interface Heard {
127130 readonly heard: ForgeEvent[];
128131 /** Quiet `run.finished` events of the last day, by id. */
@@ -190,11 +193,19 @@ export function quietRunsFor(
190193 .filter((e) => quiet.has(e.id) && repos.get(e.repoId!)?.archivedAt == null)
191194 .map((e) => ({ repoId: e.repoId!, actorId: e.actorId, id: e.id }));
192195 }
193 /** How much of a sync failure's stored reason (`PULL_REASON_MAX`, `apps/pull.ts`) a feed line shows. */
196 /**
197 * How much of a sync failure's stored reason (`PULL_REASON_MAX`, `apps/pull.ts`) a feed line shows.
198 */
194199 const SYNC_REASON_SHOWN = 120;
195200 const clip = (s: string, n = 120): string =>
196201 s.length > n ? `${s.slice(0, n - 1)}…` : s;
197202
203 const plain = <T extends { what: string; said?: string }>(c: T): T => ({
204 ...c,
205 what: plainWords(c.what),
206 ...(c.said === undefined ? {} : { said: plainWords(c.said) }),
207 });
208
198209 const slug = (r: Repo): string => `${r.ownerName}/${r.name}`;
199210 const base = (r: Repo): string => `/${r.ownerName}/${r.name}`;
200211
@@ -409,11 +420,13 @@ export function eventCandidates(
409420 if (e.kind === "clog.cleared" && now - Date.parse(e.createdAt) > CLOG_NOTE_WINDOW_MS) continue;
410421 const c = fromEvent(db, e, repo, owns(repo), readsLogs(repo), subjects);
411422 if (c)
412 out.push({
413 ...c,
414 actor: nameOf(e.actorId),
415 ...(fold === undefined ? {} : { what: `${c.what} · ${foldedWords(fold, now)}` }),
416 });
423 out.push(
424 plain({
425 ...c,
426 actor: nameOf(e.actorId),
427 ...(fold === undefined ? {} : { what: `${c.what} · ${foldedWords(fold, now)}` }),
428 }),
429 );
417430 }
418431 return out;
419432 }
@@ -492,7 +505,7 @@ export function candidatesFor(
492505 urgency: 0,
493506 });
494507 }
495 return awake(db, out, repos);
508 return awake(db, out.map(plain), repos);
496509 }
497510
498511 /** What a pull's earlier posts add to its latest: when it opened, how many reviews. */
src/feed/plain.ts added +16
@@ -0,0 +1,16 @@
1 /** Words with no raw id in them: a reason names things, it does not quote their keys. */
2
3 const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
4 const ULID = /\b[0-7][0-9A-HJKMNP-TV-Z]{25}\b/g;
5 // A hex id has a letter in it: a long run of digits is a count, a time or an amount, and stays.
outdated

Matches 12+ digit numbers (timestamps, byte counts) as ids. Require a letter a-f, e.g. (?=[0-9a-f]*[a-f]), and test that a long number is kept.

6 const HEX = /\b(?=[0-9a-f]*[a-f])[0-9a-f]{12,64}\b/gi;
7 const PREFIXED = /\b(?:event|repo|user|run|ask|decision):[\w-]{8,}/gi;
8
9 /** A raw id is no reason: a commit id keeps its first 7 characters, any other id reads "an id". */
10 export function plainWords(s: string): string {
11 return s
12 .replace(PREFIXED, "an id")
13 .replace(UUID, "an id")
14 .replace(ULID, "an id")
15 .replace(HEX, (h) => (h.length === 40 || h.length === 64 ? h.slice(0, 7) : "an id"));
16 }
src/feed/rank.ts +17
@@ -7,6 +7,7 @@
77 */
88
99 import { decay, type Affinity, type Weighted, type Why } from "./affinity.ts";
10 import { plainWords } from "./plain.ts";
1011 import type { Candidate, FeedAsk, FeedLook } from "./items.ts";
1112 import type { PathStep } from "../flow/path.ts";
1213 import type { Settled } from "./settled.ts";
@@ -104,8 +105,24 @@ interface Scored {
104105 readonly base: number;
105106 }
106107
108 export const REASON_MAX = 120;
109
110 /**
111 * A reason is always one plain sentence of at most `REASON_MAX` characters; a blank one says what
112 * the post is.
113 */
114 export function boundReason(reason: string, c: Pick<Candidate, "kind" | "app">): string {
115 const one = plainWords(reason).replace(/\s+/g, " ").trim();
116 if (one === "") return `a ${c.kind} in ${c.app}`.slice(0, REASON_MAX);
117 return one.length <= REASON_MAX ? one : `${one.slice(0, REASON_MAX - 1).trimEnd()}…`;
118 }
119
107120 /** The sentence for the term that led, worded only for an item that is placed. */
108121 function reasonOf(c: Candidate, aff: Affinity, now: number): string {
122 return boundReason(reasonWords(c, aff, now), c);
123 }
124
125 function reasonWords(c: Candidate, aff: Affinity, now: number): string {
109126 if (c.said !== undefined) return c.said;
110127 const app = aff.app(c.repoId);
111128 const actor = c.actorId === null ? aff.get("actor:") : aff.actor(c.actorId);
test/feed-reasons.test.ts added +194
@@ -0,0 +1,194 @@
1 /**
2 * Every feed item kind carries a reason: non-empty, at most 120 characters, no raw ids. The event
3 * kinds are built by the real builders in `src/feed/items.ts` from real events; the kinds read from
4 * state (ask, decision, milestone, choose) by `candidatesFor` from rows that carry an id in the
5 * field each builder words.
6 */
7 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { mkdtempSync, rmSync } from "node:fs";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { linkIssue } from "../src/actions/dependencies.ts";
outdated

This regex is never exercised against anything containing an id, so the check is vacuous. Build the candidates through the items.ts builders and add a case with an id in the clause.

12 import { assignIssue, openIssue, setIssueState } from "../src/actions/issues.ts";
13 import { createRepo } from "../src/actions/repos.ts";
14 import { recordDecision, setOutcome } from "../src/core/decisions.ts";
15 import { createIssue, getIssueById } from "../src/core/issues.ts";
16 import { getRepoById } from "../src/core/repos.ts";
17 import { setWatch } from "../src/core/watches.ts";
18 import { createApp, type App } from "../src/app.ts";
19 import type { ForgeEvent } from "../src/core/events.ts";
20 import type { Repo } from "../src/core/repos.ts";
21 import { createUser, type User } from "../src/core/users.ts";
22 import { Affinity } from "../src/feed/affinity.ts";
23 import { plainWords } from "../src/feed/plain.ts";
24 import { candidatesFor, eventCandidates, type Candidate, type FeedKind } from "../src/feed/items.ts";
25 import { rank, REASON_MAX } from "../src/feed/rank.ts";
26 import { quietLogs } from "./helpers/globals.ts";
27
28 quietLogs();
29
30 // The state-read kinds stamp rows with the clock, so the feed is read at it.
31 const NOW = Date.now();
32 const ULID = "01KGZ3V9XQ5T8M2R4W6Y0B1C2D";
33 const UUID = "3f2b8c1e-9a4d-4e6f-8b1a-5c7d9e0f1a2b";
34 const OID = "a".repeat(40);
35 const RAW_ID = /\b[0-9a-f]{8}-[0-9a-f]{4}-|\b[0-9a-f]{12,}\b|\b[0-7][0-9A-HJKMNP-TV-Z]{25}\b|\b(?:event|repo|user):[\w-]{8,}/i;
36
37 let root = "";
38 let app: App;

Non-blocking: RAW_ID is stricter than plainWords for long digit runs; reuse the same digit-vs-hex rule so the two cannot drift.

39 let user: User;
40 let repo: Repo;
41
42 beforeAll(async () => {
43 root = mkdtempSync(join(tmpdir(), "forge-feed-reasons-"));
44 app = createApp({ dataDir: root, port: 0 });
45 const made = await createUser(app.db, {
46 origin: "seed",
47 trusted: true,
48 username: "alice",
49 email: "[email protected]",
50 password: "a-good-passphrase",
51 adminIfFirst: true,
52 });
53 if (!made.ok) throw new Error(String(made.error));
54 user = made.value;
55 const r = await createRepo(app, user, { name: "site", visibility: "public" });
56 if (!r.ok) throw new Error(String(r.error));
57 repo = r.value;
58 seedState();
59 });
60
61 const STATE_KINDS = new Set<FeedKind>(["ask", "decision", "milestone", "choose"]);
62
63 /** One row behind each state-read kind, with a raw id in the words its builder reads. */
64 function seedState(): void {
65 const fresh = () => getRepoById(app.db, repo.id)!;
66 // ask: an issue assigned to the viewer; the ask line words its title.
67 const asked = createIssue(app.db, { repoId: repo.id, authorId: user.id, title: `Fix ${ULID} now` });
68 if (!asked.ok) throw new Error(asked.error);
69 assignIssue(app, user, fresh(), asked.value, user);
70 // decision: a decided land, its answer and outcome carrying ids.
71 const d = recordDecision(app.db, { kind: "land", repoId: repo.id, state: {}, answer: `ship ${ULID}`, p: 0.5, by: "alice", ms: 1 });
72 setOutcome(app.db, d.id, `ok ${UUID}`);
73 // milestone: a watched milestone with an id in its name, dropped so it says so.
74 const top = openIssue(app, user, fresh(), { title: `Gamma ${ULID}` });
75 const part = openIssue(app, user, fresh(), { title: "part" });
76 if (!top.ok || !part.ok) throw new Error("issue");
77 const linked = linkIssue(app, user, fresh(), top.value, part.value);
outdated

These four kinds never touch a builder, so RAW_ID cannot match their clean text. Drive the real ask/decision/milestone/choose builders with an id in their input and assert on the ranked reason.

78 if (!linked.ok) throw new Error(String(linked.error));
79 setWatch(app.db, user.id, top.value.id, true);
80 const closed = setIssueState(app, user, fresh(), getIssueById(app.db, top.value.id)!, "closed", { reason: "dropped" });
81 if (!closed.ok) throw new Error(String(closed.error));
82 // choose: two open variants of one header whose title carries an id.
83 for (const i of [0, 1]) {
84 const pull = createIssue(app.db, { repoId: repo.id, authorId: user.id, title: `Header ${UUID}`, kind: "pull" });
85 if (!pull.ok) throw new Error(pull.error);
86 app.db
87 .query(
88 `INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, variant_group)
89 VALUES (?1, 'main', ?2, 'a', 'b', 'hdr')`,
90 )
91 .run(pull.value.id, `hdr-${i}`);
92 }
93 }
94 afterAll(() => rmSync(root, { recursive: true, force: true }));
95
96 let n = 0;
97 const event = (kind: string, payload: Record<string, unknown>): ForgeEvent => ({
98 id: `${ULID.slice(0, 20)}${String(++n).padStart(6, "0")}`,
99 kind,
100 repoId: repo.id,
101 actorId: user.id,
102 payload,
103 createdAt: new Date(NOW - 3600_000).toISOString(),
104 });
105
106 /** One event per event-built kind, with the ids a payload can carry in the clause. */
107 const events = (): Record<string, ForgeEvent> => ({
108 run: event("run.finished", { state: "failed", kind: "deploy", runId: ULID, summary: `broke at ${UUID}` }),
109 cost: event("run.finished", { state: "ok", kind: "agent", runId: ULID, costUsd: 3, summary: `built ${ULID}` }),
110 pull: event("pull.opened", { number: 7 }),
111 look: event("look.taken", { env: "production", commitOid: OID }),
112 release: event("app.serving", { version: "0.7.251", commitOid: OID }),
113 tell: event("issue.opened", { number: 8 }),
114 reply: event("issue.commented", { number: 8, body: `see ${ULID} and ${OID}` }),
115 map: event("issue.blocked", { number: 8, blockedBy: 9 }),
116 syncFailed: event("adapter.sync_failed", { reason: `repo ${UUID} refused ${ULID}` }),
117 });
118
119 function cand(kind: FeedKind, what: string, urgency: number): Candidate {
120 return {
121 id: `${kind}:x`, kind, repoId: "r1", app: "alice/site", actorId: null, actor: null,
122 at: new Date(NOW - 3600_000).toISOString(), link: "/alice/site", what, urgency,
123 };
124 }
125
126 const built = (): Candidate[] => [
127 ...eventCandidates(app.db, user, NOW, Object.values(events()), new Map([[repo.id, repo]])),
128 ...candidatesFor(app.db, user, NOW).filter((c) => STATE_KINDS.has(c.kind)),
129 ];
130
131 const reasonsOf = (cs: readonly Candidate[], aff = new Affinity()) => rank(cs, aff, NOW).map((i) => i.reason);
132
133 const check = (list: readonly string[]) => {
134 for (const r of list) {
135 expect(r.length).toBeGreaterThan(0);
136 expect(r.length).toBeLessThanOrEqual(REASON_MAX);
137 expect(r).not.toMatch(RAW_ID);
138 }
139 };
140
141 test("the builders emit every kind", () => {
142 const kinds = new Set(built().map((c) => c.kind));
143 for (const k of ["run", "ask", "pull", "decision", "map", "cost", "tell", "reply", "look", "milestone", "choose", "release"])
144 expect(kinds.has(k as FeedKind)).toBe(true);
145 });
146
147 test("an id in an event's payload never reaches the clause", () => {
148 const cs = built();
149 const sync = cs.find((c) => c.what.startsWith("sync failed"))!;
150 expect(sync.what).not.toMatch(RAW_ID);
151 expect(sync.said).not.toMatch(RAW_ID);
152 expect(sync.what).toContain("an id");
153 expect(plainWords(`at ${OID}`)).toBe("at aaaaaaa");
154 expect(plainWords("event:abcdefgh1234")).toBe("an id");
155 });
156
157 test("an id in the state each state-read kind words never reaches its reason", () => {
158 const cs = built().filter((c) => STATE_KINDS.has(c.kind));
159 for (const k of STATE_KINDS) {
160 const of = cs.filter((c) => c.kind === k);
161 expect(of.length).toBeGreaterThan(0);
162 for (const c of of) {
163 expect(c.what).toContain("an id");
164 expect(c.what).not.toMatch(RAW_ID);
165 if (c.said !== undefined) expect(c.said).not.toMatch(RAW_ID);
166 }
167 }
168 check(reasonsOf(cs));
169 });
170
171 test("a long plain number is a count, a time or an amount, not an id: it stays", () => {
172 expect(plainWords("1700000000000 bytes at 123456789012")).toBe("1700000000000 bytes at 123456789012");
173 expect(plainWords("run deadbeef0123 broke")).toBe("run an id broke");
174 });
175
176 test("each kind's reason is bounded with recency, urgency or affinity leading", () => {
177 const cs = built();
178 check(reasonsOf(cs));
179 check(reasonsOf(cs.map((c) => ({ ...c, urgency: 8 }))));
180 const owns = new Affinity();
181 owns.add("app:r1", "owns", 9, NOW);
182 owns.add(`app:${repo.id}`, "owns", 9, NOW);
183 check(reasonsOf(cs, owns));
184 const crew = new Affinity();
185 crew.add(`actor:${user.id}`, "crew", 9, NOW);
186 check(reasonsOf(cs, crew));
187 });
188
189 test("a said sentence that is blank, over-long or full of ids is still bounded and plain", () => {
190 const said = (s: string): Candidate => ({ ...cand("milestone", "x", 0), said: s });
191 const out = reasonsOf([said(" "), said("w ".repeat(200)), said(Array(3).fill(`ids ${ULID} ${UUID}`).join(" "))]);
192 check(out);
193 expect(out.some((r) => r === "a milestone in alice/site")).toBe(true);
194 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs