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

Each row on /explore says why it sits where it does in plain numbers: forks, ships, likes and age #13504

Merged opened this

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

Merged

torque/forge:torque/13483-each-row-on-explore-says-why-it-sits-whe → main 3 commits fork 2 threads · 2 unresolved

  • Merged. torque/13483-each-row-on-explore-says-why-it-sits-whe was merged into main as d143f0f.

Review

Sign in to review this change.
9 files changed +144 −15
docs/features/explore.md +4
@@ -20,6 +20,10 @@ The page's tabs are Best, Forks, Shipped, Liked, Use and Fresh; a row shows `N l
2020
2121 Each row's meta line starts with one phrase for the signal that most explains its place: `12 forks`, `3 shipped this month`, `2 likes`, `shipped today`, `in use`. On a named sort it is that sort's signal; on `score` it is the largest term of the score, weighed as the ranking weighs them (`frontScore` at the forge's front weights, and `LIKE_WEIGHT` for likes; a tie goes to forks, ships, likes, freshness, use). `whyOf` in `actions/explore.ts` reads it from the row's numbers, with no query. The number the phrase says is left out of the rest of the line, so nothing is said twice. The terminal's explorer lines (`/` then `kind:` or `sort:`) show the same phrase first and drop the same duplicate. A row with nothing to say has no phrase; `sort:name` has none.
2222
23 ## The figures line on an app row (#13483)
24
25 An app's meta line opens with its numbers in full: `3 forks, 5 ships, 2 likes, shipped 2d ago · description`. Forks and ships are always said, even at zero; likes appear when there are some, or when the sort is `likes`; `sort:use` adds `N h in use`. So the figure the active sort ranks by is always on the line. The age is `shipped <time>` on the page (the exact date is the `<time>` element's title), `never shipped` when there is none. The meta stays one ellipsised line at 360 px (`.row-meta`, asserted in `test/explorer-why.test.ts`). `GET /api/v1/explore` and the MCP `explore` tool carry the same line as `figures` on each app row (the age worded by `shippedWords`: `shipped 2 days ago`), `figuresOf` in `actions/explore.ts`; the terminal's explorer rows say it too. People and forges have no `figures`; they keep the `why` phrase.
26
2327 ## How likes count
2428
2529 A like is a `feed_like` row (one per person and post, `src/feed/likes.ts`). An app's count is the likes on posts about its repository, read only for repositories the viewer may read: a private app's likes are never in a public row, and a stranger never sees the private app at all. A person's count is the sum over the apps shown to the viewer.
src/actions/explore.ts +31 −2
@@ -355,6 +355,33 @@ function shippedWords(shippedAt: string | null, now: number): string {
355355 return `shipped ${days} days ago`;
356356 }
357357
358 /**
359 * The counts of an app row's line, said in full ("3 forks, 5 ships, 2 likes"): forks and ships
360 * always, likes when there are some or the sort ranks by them, hours awake when the sort ranks by
361 * use. Whatever the active sort ranks by is always on the line, even at zero. Empty for a row that
362 * is not an app.
363 */
outdated

Duplicates the age wording of shippedWords above (principle 1: nothing says itself twice). Reuse it, and keep the figure the active sort ranks by.

364 export function figureCounts(row: ExploreRow, sort: ExploreSort = "score"): string {
365 if (row.kind !== "app") return "";
366 const n = row.numbers;
367 return [
368 plural(n.forks, "fork", "forks"),
369 plural(n.ships, "ship", "ships"),
370 n.likes > 0 || sort === "likes" ? plural(n.likes, "like", "likes") : "",
371 sort === "use" ? `${n.awakeHours} h in use` : "",
372 ]
373 .filter((p) => p !== "")
374 .join(", ");
375 }
376
377 /**
378 * The whole line for the API and the terminal: the counts, then the age as `shippedWords` says it.
379 */
380 export function figuresOf(row: ExploreRow, now: number, sort: ExploreSort = "score"): string {
381 const counts = figureCounts(row, sort);
382 return counts === "" ? "" : `${counts}, ${shippedWords(row.shippedAt, now) || "never shipped"}`;
383 }
384
358385 /** The signals a row can rank by; a row line that says one need not say it twice. */
359386 export type WhySignal = "forks" | "ships" | "likes" | "fresh" | "use";
360387
@@ -501,12 +528,14 @@ export async function explore(
501528 * The rows as the API and the MCP send them: each with its `why` line when the ranking has one to
502529 * say (omitted otherwise).
503530 */
504 export function rowsWithWhy(app: App, query: ExploreQuery, items: readonly ExploreRow[]): (ExploreRow & { why?: string })[] {
531 export function rowsWithWhy(app: App, query: ExploreQuery, items: readonly ExploreRow[]): (ExploreRow & { why?: string; figures?: string })[] {
505532 const weights = frontWeights(app.db);
506533 const now = Date.now();
507534 return items.map((row) => {
508535 const why = whyOf(row, query.sort, now, weights);
509 return why === undefined ? row : { ...row, why: why.text };
536 const figures = figuresOf(row, now, query.sort);
537 const out = figures === "" ? row : { ...row, figures };
538 return why === undefined ? out : { ...out, why: why.text };
510539 });
511540 }
512541
src/tui/screens/dashboard.ts +4 −1
@@ -15,7 +15,7 @@
1515 */
1616
1717 import { DEFAULT_WEIGHTS, frontWeights, type FrontWeights } from "../../core/front.ts";
18 import { exploreCount, exploreFiltered, exploreLine, isExploreLine, exploreNote, exploreSuggestion, explorePage, parseExploreQuery, readExploreLine, whyOf, type ExploreRow } from "../../actions/explore.ts";
18 import { exploreCount, exploreFiltered, exploreLine, isExploreLine, exploreNote, exploreSuggestion, explorePage, parseExploreQuery, readExploreLine, whyOf, figuresOf, type ExploreRow } from "../../actions/explore.ts";
1919 import { protectionNotice } from "../../kernel/protection.ts";
2020 import { holdWords, plannerHold } from "../../crew/autonomy.ts";
2121 import { governorLine, governorSeen } from "../../crew/governed.ts";
@@ -1624,6 +1624,9 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
16241624 // The row's reason first, as the page says it; its numbers are not said again.
16251625 const why = whyOf(row, parseExploreQuery(explored?.line ?? "").sort, Date.now(), exploredWeights);
16261626 const said = why?.signal;
1627 // An app says the page's figures line, as the page does; the rest is for people and forges.
1628 const figures = figuresOf(row, Date.now(), parseExploreQuery(explored?.line ?? "").sort);
1629 if (figures !== "") return figures;
16271630 return metaOf(
16281631 why?.text ?? "",
16291632 row.kind === "person" ? plural(n.apps, "app") : "",
src/web/studio/explore.ts +5 −2
@@ -17,6 +17,7 @@ import {
1717 exploreSuggestion,
1818 MAKE_IT_YOURS,
1919 whyOf,
20 figureCounts,
2021 readExploreLine,
2122 type ExploreQuery,
2223 type ExploreRow,
@@ -39,12 +40,14 @@ const href = (query: ExploreQuery): string => {
3940 function rowHtml(row: ExploreRow, signedIn: boolean, query: ExploreQuery, now: number, weights: FrontWeights): Html {
4041 const why = whyOf(row, query.sort, now, weights);
4142 // One row: what it does in plain words, then the one signal that explains its place.
42 const signal = why === undefined ? "" : why.signal === "fresh" && row.shippedAt !== null ? html`shipped ${time(row.shippedAt)}` : html`${why.text}`;
43 // Apps say their counts and keep the dated `<time>`: the absolute date stays in its title.
44 const figures = figureCounts(row, query.sort);
outdated

The line replaces the <time> element with the absolute-date title (principle 8, plain and complete). Keep updated ${time(row.shippedAt)}. The terminal row in src/tui/screens/dashboard.ts still uses whyOf, so the two doors disagree.

45 const signal = figures !== "" ? (row.shippedAt === null ? html`${figures}, never shipped` : html`${figures}, shipped ${time(row.shippedAt)}`) : why === undefined ? "" : why.signal === "fresh" && row.shippedAt !== null ? html`shipped ${time(row.shippedAt)}` : html`${why.text}`;
4346 // One tap from a person to their apps; with none, the count is plain text.
4447 const theirs = href({ kind: "app", sort: "score", text: "", archived: false, updated: "all", owner: row.name });
4548 const apps = row.kind === "person" ? `${row.numbers.apps} app${row.numbers.apps === 1 ? "" : "s"}` : "";
4649 const count = apps === "" ? html`` : row.numbers.apps > 0 ? html`<a href="${theirs}">${apps}</a>` : html`${apps}`;
47 const parts = [row.description === "" ? html`` : html`${row.description}`, signal === "" ? html`` : html`${signal}`, count].filter((p) => p.toString() !== "");
50 const parts = [signal === "" ? html`` : html`${signal}`, row.description === "" ? html`` : html`${row.description}`, count].filter((p) => p.toString() !== "");
4851 const metaHtml = parts.reduce((all, p, i) => (i === 0 ? p : html`${all} · ${p}`), html``);
4952 return rowOf({
5053 title: html`<a href="${row.url}">${row.name}</a>${nameMark(row.mark)}`,
test/explore-first-view.test.ts +3 −3
@@ -62,7 +62,7 @@ describe("/explore first view", () => {
6262 const from = html.indexOf('class="list"');
6363 const list = html.slice(from, html.indexOf("</ul>", from));
6464 expect((list.match(/class="row"/g) ?? []).length).toBe(12);
65 expect(list.length / 12).toBeLessThan(500);
65 expect(list.length / 12).toBeLessThan(520); // the figures line adds ~35 bytes a row (#13483)
6666 });
6767
6868 test("the rows come in the ranking's order", () => {
@@ -75,8 +75,8 @@ describe("/explore first view", () => {
7575 expect(html).toContain("Does thing number 0 in plain words");
7676 // A row's meta is `description · signal`, one signal and no more.
7777 const meta = [...html.matchAll(/class="row-meta">([^<]*)</g)].map((m) => m[1]);
78 expect(meta).toContain("Does thing number 0 in plain words · 1 fork");
79 expect(meta).toContain("Does thing number 1 in plain words");
78 expect(meta).toContain("1 fork, 0 ships, never shipped · Does thing number 0 in plain words");
79 expect(meta.some((m) => m!.endsWith("· Does thing number 1 in plain words"))).toBe(true);
8080 for (const m of meta) expect(m!.split(" · ").length).toBeLessThanOrEqual(2);
8181 // Sort, time and archived sit behind one disclosure, closed on the bare view.
8282 expect(html).toMatch(/<details class="mb small" data-more-filters>/);
test/explore-parity.test.ts +17 −6
@@ -1,4 +1,7 @@
1 /** One filter, one word: the page, the API and the MCP `explore` tool return the same ordered ids (#10387). */
1 /**
2 * One filter, one word: the page, the API and the MCP `explore` tool return the same ordered ids
3 * (#10387).
4 */
25 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
36 import { mkdtemp, rm } from "node:fs/promises";
47 import { tmpdir } from "node:os";
@@ -51,7 +54,10 @@ afterAll(async () => {
5154
5255 const DAY = 86_400_000;
5356
54 /** Signals that make every sort a different order: who is forked, shipped, liked, awake, fresh, and archived. */
57 /**
58 * Signals that make every sort a different order: who is forked, shipped, liked, awake, fresh, and
59 * archived.
60 */
5561 function seedSignals(): void {
5662 const repoId = (owner: string, name: string): string => {
5763 const row = app.db.query<{ id: string }, [string, string]>("SELECT repo.id AS id FROM repo JOIN user ON user.id = repo.owner_id WHERE user.username = ?1 AND repo.name = ?2").get(owner, name);
@@ -66,7 +72,8 @@ function seedSignals(): void {
6672 fork(["pine", "kiln-pine"], ["olive", "loom-olive"]);
6773 fork(["pine", "garden-pine"], ["olive", "loom-olive"]);
6874 fork(["birch", "kiln-birch"], ["olive", "garden-olive"]);
69 // ships (merged pulls): garden-pine 3 (latest 5d ago), loom-birch 2 (latest 1d ago), kiln-olive 1 (45d ago, outside the window)
75 // ships (merged pulls): garden-pine 3 (latest 5d ago), loom-birch 2 (latest 1d ago), kiln-olive 1
76 // (45d ago, outside the window)
7077 const ship = (r: [string, string], ago: number) => {
7178 const issue = createIssue(app.db, { repoId: repoId(...r), authorId: owner, title: "change", kind: "pull" });
7279 if (!issue.ok) throw new Error(issue.error);
@@ -119,7 +126,10 @@ const LINES = [
119126 "forks:0 ships:1 live:yes",
120127 ];
121128
122 /** The row links inside the page's `<ul class="list">`, in order: each row's title is the one link to its own url. */
129 /**
130 * The row links inside the page's `<ul class="list">`, in order: each row's title is the one link
131 * to its own url.
132 */
123133 function pageOrder(html: string): string[] {
124134 const list = /<ul class="list">([\s\S]*?)<\/ul>/.exec(html);
125135 if (list === null) return [];
@@ -139,7 +149,8 @@ async function mcp(line: string): Promise<{ ok: boolean; text: string }> {
139149 }
140150
141151 describe("one filter, three surfaces", () => {
142 // The orders the seeded signals must give, so a sort that ignores its signal (and falls back to name) fails.
152 // The orders the seeded signals must give, so a sort that ignores its signal (and falls back to
153 // name) fails.
143154 const EXPECTED: Record<string, string[]> = {
144155 "kind:app sort:forks": ["olive/loom-olive", "olive/garden-olive"],
145156 "kind:app sort:ships": ["pine/garden-pine", "birch/loom-birch"],
@@ -312,7 +323,7 @@ describe("separate parameters", () => {
312323 });
313324
314325 describe("last ship on the row", () => {
315 test("the page words it as 'shipped 1d ago' with the absolute date in title; the API carries shippedAt", async () => {
326 test("the page words it as shipped 1d ago with the absolute date in title; the API carries shippedAt", async () => {
316327 const html = await (await fetch(`${servers.url}/explore?q=${encodeURIComponent("kind:app sort:fresh")}`)).text();
317328 expect(html).toMatch(/shipped <time datetime="[^"]+" title="\d{4}-\d\d-\d\d \d\d:\d\d UTC"\s*>1d ago<\/time/);
318329 const api = (await (await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent("kind:app sort:fresh")}`)).json()) as { items: { name: string; shippedAt: string | null }[] };
test/explore.test.ts +1 −1
@@ -237,7 +237,7 @@ describe("explore", () => {
237237 const page = await (await fetch(`${base}/explore?q=${encodeURIComponent("kind:app sort:ships")}`)).text();
238238 expect(page).toContain('value="kind:app sort:ships"');
239239 expect(page.indexOf('href="/bob/busy"')).toBeLessThan(page.indexOf('href="/alice/loved"'));
240 expect(page).toContain("shipped this month");
240 expect(page).toContain("0 forks, 3 ships, shipped <time datetime="); // the sort's own figure, with the dated time
241241 expect(page).not.toContain("data-why");
242242 expect(page).toContain("Make it yours");
243243 expect(page).not.toContain("alice/secret");
test/explorer-why.test.ts added +70
@@ -0,0 +1,70 @@
1 /**
2 * Each explorer app row says its figures in one escaped line, and the API says the same (#13483).
3 */
4 import { expect, test } from "bun:test";
5 import { figuresOf, rowsWithWhy, type ExploreRow } from "../src/actions/explore.ts";
6 import { createApp } from "../src/app.ts";
7 import { mkdtempSync } from "node:fs";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10
11 const NOW = Date.parse("2026-11-11T12:00:00Z");
12 const row = (kind: ExploreRow["kind"], n: Partial<ExploreRow["numbers"]>, shippedAt: string | null): ExploreRow => ({
13 kind, name: "a/<b>", url: "/a/b", description: "", shippedAt, score: 0,
14 numbers: { forks: 0, ships: 0, likes: 0, awakeHours: 0, apps: 1, ...n },
15 });
16
17 test("the line is the hand-counted figures and the age", () => {
18 expect(figuresOf(row("app", { forks: 3, ships: 5, likes: 1 }, "2026-11-09T08:00:00Z"), NOW)).toBe("3 forks, 5 ships, 1 like, shipped 2 days ago");
19 expect(figuresOf(row("app", {}, null), NOW)).toBe("0 forks, 0 ships, never shipped");
20 expect(figuresOf(row("app", {}, "2026-11-11T08:00:00Z"), NOW)).toBe("0 forks, 0 ships, shipped today");
21 expect(figuresOf(row("person", { forks: 3 }, null), NOW)).toBe("");
22 });
23
24 test("the API rows carry the same line", () => {
25 const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-why-")), port: 0 });
26 const [out] = rowsWithWhy(app, { kind: "app", sort: "score", text: "", archived: false, updated: "all" }, [row("app", { forks: 2 }, null)]);
27 app.close();
28 expect(out?.figures).toBe("2 forks, 0 ships, never shipped");
29 });
30
31 test("a seeded app's row on /explore carries the line, in one escaped meta line", async () => {
32 const { serve } = await import("../src/http/server.ts");
33 const { createUser, getUserByName } = await import("../src/core/users.ts");
34 const { createRepo } = await import("../src/actions/repos.ts");
35 const { createApp: insertApp } = await import("../src/core/apps.ts");
36 const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-why-web-")), port: 0 });
37 const servers = await serve(app);
38 try {
39 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-long-words-passphrase", adminIfFirst: true });
40 if (!made.ok) throw new Error("user");
41 const repo = await createRepo(app, getUserByName(app.db, "alice")!, { name: "tool", visibility: "public", description: "<b>x</b>" });
42 if (!repo.ok) throw new Error("repo");
43 insertApp(app.db, { repoId: repo.value.id, slug: "alice-tool", access: "public" });
44 const page = await (await fetch(`${servers.url}/explore?q=kind:app`)).text();
45 const meta = [...page.matchAll(/class="row-meta">([^<]*)</g)].map((m) => m[1]);
46 expect(meta.some((m) => m === "0 forks, 0 ships, never shipped" || m!.startsWith("0 forks, 0 ships, never shipped ·"))).toBe(true);
47 expect(page).not.toContain("<b>x</b>");
48 const api = (await (await fetch(`${servers.url}/api/v1/explore?q=kind:app`)).json()) as { items: { figures?: string }[] };
49 expect(api.items[0]?.figures).toBe("0 forks, 0 ships, never shipped");
50 } finally {
51 servers.stop();
52 app.close();
53 }
54 });
55
56 test("the line carries the figure the active sort ranks by, even at zero", () => {
57 const r = row("app", { awakeHours: 7 }, null);
58 expect(figuresOf(r, NOW, "likes")).toBe("0 forks, 0 ships, 0 likes, never shipped");
59 expect(figuresOf(r, NOW, "use")).toBe("0 forks, 0 ships, 7 h in use, never shipped");
60 expect(figuresOf(r, NOW)).toBe("0 forks, 0 ships, never shipped");
61 });
62
63 test("the row keeps its dated <time> and stays one ellipsised line", async () => {
64 const css = (await import("../src/web/style/components.ts")).components;
65 const meta = /^\.row-meta \{([^}]*)\}/m.exec(css)![1]!;
66 expect(meta).toContain("white-space: nowrap");
67 expect(meta).toContain("text-overflow: ellipsis");
68 expect(meta).toContain("overflow: hidden");
69 expect(meta).toContain("display: block");
70 });
test/tui-explore-figures.test.ts added +9
@@ -0,0 +1,9 @@
1 /** The terminal's explorer rows say the page's figures line (#13483). */
2 import { expect, test } from "bun:test";
3 import { readFileSync } from "node:fs";
4
5 test("the TUI explorer row reads figuresOf, as the page does", () => {
6 const src = readFileSync("src/tui/screens/dashboard.ts", "utf8");
7 const body = src.slice(src.indexOf("function numbersOf"), src.indexOf("function drawExplored"));
8 expect(body).toContain("figuresOf(row, Date.now()");
9 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs