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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13397-every-feed-item-kind-carries-a-reason-se → main 4 commits fork 5 threads · 5 unresolved
docs/FEED.md +6 −3
| @@ -6,8 +6,8 @@ one sentence saying why it is there. | ||
| 6 | 6 | `GET /api/v1/feed?limit=&cursor=` → `{ items, next_cursor }`, for the signed-in |
| 7 | 7 | viewer only. An item is `{ id, kind, app, actor, at, link, what, reason, |
| 8 | 8 | 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 | |
| 11 | 11 | them. The MCP tool `feed { limit, cursor }` answers the same. |
| 12 | 12 | |
| 13 | 13 | `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 | ||
| 61 | 61 | the viewer's own merges/proposals/tells and ledger outcomes, then moved by |
| 62 | 62 | interactions; a dismissal is −4, a mute −8 and hides the app. Each item |
| 63 | 63 | 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 | |
| 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`). | |
| 65 | 68 | |
| 66 | 69 | Muting hides an app's items except asks: what waits on a person is never |
| 67 | 70 | 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"; | ||
| 40 | 40 | import { hotSays, standingHot, standingWide, wideSays } from "../crew/hot_files.ts"; |
| 41 | 41 | import { conflictsOf, conflictWords } from "../crew/stale_asks.ts"; |
| 42 | 42 | import { ago } from "./rank.ts"; |
| 43 | import { plainWords } from "./plain.ts"; | |
| 43 | 44 | import { askLinesFor } from "../web/studio/asks.ts"; |
| 44 | 45 | |
| 45 | 46 | export type FeedKind = |
| @@ -122,7 +123,9 @@ const cheap = (e: ForgeEvent): boolean => { | ||
| 122 | 123 | return !(typeof cost === "number" && cost >= COST_FLOOR_USD); |
| 123 | 124 | }; |
| 124 | 125 | |
| 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 | */ | |
| 126 | 129 | interface Heard { |
| 127 | 130 | readonly heard: ForgeEvent[]; |
| 128 | 131 | /** Quiet `run.finished` events of the last day, by id. */ |
| @@ -190,11 +193,19 @@ export function quietRunsFor( | ||
| 190 | 193 | .filter((e) => quiet.has(e.id) && repos.get(e.repoId!)?.archivedAt == null) |
| 191 | 194 | .map((e) => ({ repoId: e.repoId!, actorId: e.actorId, id: e.id })); |
| 192 | 195 | } |
| 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 | */ | |
| 194 | 199 | const SYNC_REASON_SHOWN = 120; |
| 195 | 200 | const clip = (s: string, n = 120): string => |
| 196 | 201 | s.length > n ? `${s.slice(0, n - 1)}…` : s; |
| 197 | 202 | |
| 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 | ||
| 198 | 209 | const slug = (r: Repo): string => `${r.ownerName}/${r.name}`; |
| 199 | 210 | const base = (r: Repo): string => `/${r.ownerName}/${r.name}`; |
| 200 | 211 | |
| @@ -409,11 +420,13 @@ export function eventCandidates( | ||
| 409 | 420 | if (e.kind === "clog.cleared" && now - Date.parse(e.createdAt) > CLOG_NOTE_WINDOW_MS) continue; |
| 410 | 421 | const c = fromEvent(db, e, repo, owns(repo), readsLogs(repo), subjects); |
| 411 | 422 | 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 | ); | |
| 417 | 430 | } |
| 418 | 431 | return out; |
| 419 | 432 | } |
| @@ -492,7 +505,7 @@ export function candidatesFor( | ||
| 492 | 505 | urgency: 0, |
| 493 | 506 | }); |
| 494 | 507 | } |
| 495 | return awake(db, out, repos); | |
| 508 | return awake(db, out.map(plain), repos); | |
| 496 | 509 | } |
| 497 | 510 | |
| 498 | 511 | /** 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 @@ | ||
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | 9 | import { decay, type Affinity, type Weighted, type Why } from "./affinity.ts"; |
| 10 | import { plainWords } from "./plain.ts"; | |
| 10 | 11 | import type { Candidate, FeedAsk, FeedLook } from "./items.ts"; |
| 11 | 12 | import type { PathStep } from "../flow/path.ts"; |
| 12 | 13 | import type { Settled } from "./settled.ts"; |
| @@ -104,8 +105,24 @@ interface Scored { | ||
| 104 | 105 | readonly base: number; |
| 105 | 106 | } |
| 106 | 107 | |
| 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 | ||
| 107 | 120 | /** The sentence for the term that led, worded only for an item that is placed. */ |
| 108 | 121 | 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 { | |
| 109 | 126 | if (c.said !== undefined) return c.said; |
| 110 | 127 | const app = aff.app(c.repoId); |
| 111 | 128 | 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 | }); |
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.