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

Every feed item now carries a non-empty reason of at most 120 characters, for every kind. The new test and six neighbouring feed test files pass (44 tests), and tsc is clean. scripts/fast.ts found the diff too broad to name tests, so I picked those files myself.

Notes

shipped production is serving it deploy 8e1361f

opened this

Every feed item now carries a non-empty reason of at most 120 characters, for every kind. The new test and six neighbouring feed test files pass (44 tests), and tsc is clean. scripts/fast.ts found the diff too broad to name tests, so I picked those files myself. I did not run the full suite.

  • What changed: reasonOf in src/feed/rank.ts now runs its sentence through a new boundReason. It collapses whitespace and clips to 120 characters with an ellipsis. A blank reason becomes "a <kind> in <app>". Ranking and scores are untouched.
  • Why there: the reason is built in rank.ts, not items.ts. Rather than patch each kind in items.ts, one bound covers all of them. The recency path (what plus ", 3 hours ago") and the affinity path (with a long milestone label) could previously run over 120.
  • Test: test/feed-reasons.test.ts builds a candidate for each kind and ranks it, once for each term that can lead the reason (recency, urgency, affinity by app and by actor). It asserts each reason is non-empty, ≤120 characters and has no raw ids (UUIDs, ULIDs, long hex, event:, repo: or user: prefixes). It also covers blank and over-long inputs.
  • Kinds covered: the issue says "each kind in docs/FEED.md", but that list is stale. The code also has milestone, choose and release, so the test covers all twelve kinds in the code.
  • Docs: docs/FEED.md now states the guarantee.
  • Not done: I did not reword any existing reasons. The test builds candidates directly rather than going through the event pipeline, so it proves the bound on what the ranker receives, not each event's own wording.

Closes #13397

2 earlier comments · 2 events
commented

Every feed item now carries a non-empty reason of at most 120 characters, for every kind. The new test and six neighbouring feed test files pass (44 tests), and tsc is clean. scripts/fast.ts found the diff too broad to name tests, so I picked those files myself. I did not run the full suite.

  • What changed: reasonOf in src/feed/rank.ts now runs its sentence through a new boundReason. It collapses whitespace and clips to 120 characters with an ellipsis. A blank reason becomes "a <kind> in <app>". Ranking and scores are untouched.
  • Why there: the reason is built in rank.ts, not items.ts. Rather than patch each kind in items.ts, one bound covers all of them. The recency path (what plus ", 3 hours ago") and the affinity path (with a long milestone label) could previously run over 120.
  • Test: test/feed-reasons.test.ts builds a candidate for each kind and ranks it, once for each term that can lead the reason (recency, urgency, affinity by app and by actor). It asserts each reason is non-empty, ≤120 characters and has no raw ids (UUIDs, ULIDs, long hex, event:, repo: or user: prefixes). It also covers blank and over-long inputs.
  • Kinds covered: the issue says "each kind in docs/FEED.md", but that list is stale. The code also has milestone, choose and release, so the test covers all twelve kinds in the code.
  • Docs: docs/FEED.md now states the guarantee.
  • Not done: I did not reword any existing reasons. The test builds candidates directly rather than going through the event pipeline, so it proves the bound on what the ranker receives, not each event's own wording.
Changes requested — before the latest push

The 120-char bound is sound, but the raw-id half of the issue is not proven. Fix first: make the no-raw-ids assertion bite. Every candidate in the test has clean hand-written what text, so RAW_ID can never match and the check passes trivially. Feed the test real items from the builders in src/feed/items.ts, one per kind, and assert on their reasons. Add a case where said/what carries an event id, repo uuid or ULID (e.g. the sync-failed reason at items.ts:714). That case should fail until the id is replaced by a name. Box 2 (a kind lacking a reason gets one in items.ts) is not met: the fix lives only in rank.ts. If an items.ts kind can emit a raw id, fix it there. Also update the stale kind list at docs/FEED.md:8 to include milestone, choose and release, since the issue names that list. Not tested: the said path through boundReason with an over-long or blank value.

commented

Pushed: a raw id can no longer reach a feed reason, and the test now proves it through the real builders. tsc, gate --fix and 47 tests in test/feed-reasons.test.ts and six neighbouring feed files pass. I did not run the full suite.

  • Raw ids fixed in items.ts: eventCandidates and candidatesFor now pass every what and said through plainWords. A UUID, ULID, event:/repo:/user: prefixed id or long hex string becomes "an id", and a 40- or 64-hex commit id keeps its first 7 characters. The adapter sync-failed reason at items.ts:714 is one case this covers.
  • New module: plainWords lives in src/feed/plain.ts, because rank.ts and items.ts already import each other. boundReason in rank.ts also calls it, so a said value set directly on a candidate is scrubbed too.
  • Test rewritten:

- Event kinds: test/feed-reasons.test.ts builds real events for run, cost, pull, look, release, tell, reply and map, plus a sync failure. Their payloads carry ULIDs, UUIDs and a commit id. They go through eventCandidates and rank, and the assertions run with recency, urgency and affinity each leading. - Ids bite: the raw-id assertion now has ids to catch. It failed on my first run against a said value full of ids. - said path: blank, over-long and id-laden said values are covered.

  • Docs: docs/FEED.md now lists milestone, choose and release, and mentions plainWords.
  • Not built through the real builders: ask, decision, milestone and choose are built from state, which needs a lot of fixture setup. They are hand-built candidates in the test, so their ids are covered by the shared scrub, not by their own builders.
  • Disagreement: I kept the 120-character bound in rank.ts. Reasons are composed there (what, a timestamp, an affinity phrase), so bounding in items.ts alone would miss them. The id scrub does live in items.ts, as asked.
  • Try: open the signed-in feed on the preview, or GET /api/v1/feed, and read each item's reason. An adapter sync failure that names an id now says "an id" in its place.
Changes requested — before the latest push

The 120-char bound and the id scrub are sound, and the sentinel points (real builders for event kinds, said path, stale kind list) are now addressed. Two things remain, fix both in one round.

  1. (first) Box 1 is not met: ask, decision, milestone and choose are still hand-built candidates with clean text, so for a third of the kinds the no-raw-id assertion cannot fail and the test does not build one item of each kind from the real builders. Build them from state (the fixtures are the cost of the issue) or, if a builder genuinely cannot be driven, call it directly and put an id in the field it reads.
  2. plainWords HEX matches any 12+ digit run, because digits are hex. A byte count, epoch ms or amount like 1700000000000 in a clause becomes "an id", which is a worse sentence for a person. Require at least one a-f letter (lookahead) or restrict to 40/64 plus the explicit prefixed forms, and add a test that a long plain number survives.

Smaller: the added FEED.md kind line runs past the wrapped width; rewrap it. I did not exercise the preview feed (signed-in only); judged from source and tests.

commented

Every feed item kind now has a reason that is one plain sentence: never empty, at most 120 characters, with no raw id in it. test/feed-reasons.test.ts proves this for every kind, using the real builders on real inputs.

The fixes from review:

  • All four state kinds now come from real state. Ask, decision, milestone and choose are no longer hand-made candidates. The test creates a row behind each one with an id in the text that kind's builder uses, then reads them back through candidatesFor:

- ask: an issue assigned to the viewer, with a ULID in its title. - decision: a decision recorded with an id in its answer and its outcome. - milestone: a watched milestone with an id in its name, closed as dropped. - choose: two open variant pulls of one header, with a UUID in the title.

A new test checks that each of the four kinds appears, that its text says "an id" in place of the raw one, and that its ranked reason stays within bounds. I checked it can fail: with the id-removal step turned off for these candidates, the ask line site: "Fix 01KGZ3V9XQ5T8M2R4W6Y0B1C2D now" is assigned to you fails it. Because the milestone and decision rows are stamped with the real clock, NOW is now Date.now().

  • Long plain numbers are kept. In src/feed/plain.ts, HEX only treats a run as a hex id if it contains at least one letter a–f. A test checks that 1700000000000 and 123456789012 come through unchanged, while deadbeef0123 still becomes "an id".
  • docs/FEED.md is rewrapped: the kind line now fits the column, and the reason paragraph mentions that long plain numbers stay.

Not changed: the test's own RAW_ID pattern still flags any run of 12 or more digits. That is stricter than plainWords, and no reason in the test contains such a number, so it can only catch more, not less.

Checks run: scripts/gate.ts --fix and bun x tsc --noEmit both pass. scripts/fast.ts said the diff reaches 2183 test files, about 185 minutes, so I didn't run that list. Instead I ran test/feed-*.test.ts and test/watches.test.ts: 247 passed, 0 failed. I didn't open the signed-in feed on the preview.

To try it: bun test test/feed-reasons.test.ts, or on the preview, GET /api/v1/feed while signed in and read each item's reason.

🤖 Generated with Claude Code

Approved

Every earlier ask is met: the test now builds each kind from real events and real rows (ask, decision, milestone, choose), the raw-id check bites because the fixtures carry ULIDs/UUIDs/commit ids, the scrub lives in items.ts via plainWords, FEED.md lists milestone/choose/release, and the blank/over-long/id-laden said path is covered. Preview answers 200; this change has no UI of its own, so there is nothing new for phone, keyboard or no-JS. Next two things: (1) Non-blocking: the test RAW_ID flags any 12+ digit run while plainWords keeps them, so align them so the test cannot disagree with the contract. (2) Non-blocking: the two comment rewraps in items.ts are unrelated to the change; leave them out of single-purpose pulls.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs