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

/explore sorts by newest or most forked with two plain links kept in the URL, the active one marked #13556

Merged opened this

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

Merged

scout/forge:scout/13523-explore-sorts-by-newest-or-most-forked-w → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/13523-explore-sorts-by-newest-or-most-forked-w was merged into main as cd82f91.

Review

Sign in to review this change.
7 files changed +90 −16
docs/features/explore.md +4 −3
@@ -12,13 +12,14 @@
1212 | `likes` | likes on posts about the app |
1313 | `use` | hours awake in the last 30 days |
1414 | `fresh` | the last merge |
15 | `new` | the most recently made app first (a person by their newest app) |
1516 | `name` | A to Z |
1617
17 The page's tabs are Best, Forks, Shipped, Liked, Use and Fresh; a row shows `N likes` when N > 0, on the web and in the terminal.
18 The page's tabs are Best, Forks, Shipped, Liked, Use, Fresh and Newest; a row shows `N likes` when N > 0, on the web and in the terminal.
1819
1920 ## Why a row ranks where it does (#11296)
2021
21 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.
22 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` and `sort:new` have none.
2223
2324 ## How likes count
2425
@@ -36,7 +37,7 @@ What a person filters on `/explore` an agent filters with the same words. Each f
3637
3738 | the page offers | the parameter | API `GET /api/v1/explore` | MCP `explore` |
3839 |---|---|---|---|
39 | Best / Forks / Shipped / Liked / Use / Fresh | `sort=score` `forks` `ships` `likes` `use` `fresh` (`name` by hand) | `?sort=forks` | `{ sort: "forks" }` |
40 | Best / Forks / Shipped / Liked / Use / Fresh / Newest | `sort=score` `forks` `ships` `likes` `use` `fresh` `new` (`name` by hand) | `?sort=forks` | `{ sort: "forks" }` |
4041 | All / Apps / People / Forges (admin) | `kind=app` `person` `forge` | `?kind=app` | `{ kind: "app" }` |
4142 | Any time / Today / This week / This month | `since=1d` `7d` `30d` (`updated=` is the same) | `?since=7d` | `{ since: "7d" }` |
4243 | Show archived | `archived=yes` | `?archived=yes` | `{ archived: "yes" }` |
src/actions/explore.ts +12 −2
@@ -30,7 +30,7 @@ import {
3030 type FrontWeights,
3131 } from "../core/front.ts";
3232 import { isSafeName } from "../git/guard.ts";
33 import { canEnterApp, listReposVisibleTo, type Repo } from "../core/repos.ts";
33 import { canEnterApp, listReposVisibleTo, repoDatesFor, type Repo } from "../core/repos.ts";
3434 import { getUsersByIds, isActive, type User } from "../core/users.ts";
3535 import { rankInputs } from "../core/rank_inputs.ts";
3636 import { writeStamp } from "../core/write_clock.ts";
@@ -46,6 +46,7 @@ export type ExploreSort =
4646 | "likes"
4747 | "use"
4848 | "fresh"
49 | "new"
4950 | "name";
5051
5152 export interface ExploreQuery {
@@ -100,6 +101,7 @@ const SORTS: readonly ExploreSort[] = [
100101 "likes",
101102 "use",
102103 "fresh",
104 "new",
103105 "name",
104106 ];
105107
@@ -379,7 +381,7 @@ export function whyOf(
379381 fresh: shippedWords(row.shippedAt, now),
380382 use: n.awakeHours > 0 ? "in use" : "",
381383 };
382 if (sort === "name") return undefined;
384 if (sort === "name" || sort === "new") return undefined;
383385 if (sort !== "score") {
384386 const signal: WhySignal = sort;
385387 return text[signal] === "" ? undefined : { signal, text: text[signal] };
@@ -419,6 +421,8 @@ export interface ExploreRow {
419421 readonly apps: number;
420422 };
421423 readonly shippedAt: string | null;
424 /** When the app was made (a person: their newest app); read only for `sort:new`. */
425 readonly createdAt?: string;
422426 readonly score: number;
423427 /** An app's repository, for "Make it yours". */
424428 readonly repo?: { readonly owner: string; readonly name: string; readonly id: string; readonly branch: string; readonly public: boolean };
@@ -656,6 +660,8 @@ function rank(
656660 );
657661 },
658662 );
663 // Creation dates cost a read, so only the newest sort makes it (one chunked query).
664 const dates = query.sort === "new" ? repoDatesFor(db, appRepos.map((r) => r.id)) : undefined;
659665 const weights = frontWeights(db);
660666 const signals = frontSignals(
661667 db,
@@ -706,6 +712,7 @@ function rank(
706712 apps: 1,
707713 },
708714 shippedAt: s.shippedAt,
715 ...(dates?.get(repo.id) === undefined ? {} : { createdAt: dates.get(repo.id)!.createdAt }),
709716 score: frontScore(s, now, weights) + LIKE_WEIGHT * Math.log1p(liked),
710717 repo: {
711718 owner: repo.ownerName,
@@ -727,6 +734,7 @@ function rank(
727734 .filter((t): t is string => t !== null)
728735 .sort()
729736 .at(-1);
737 const newest = [was?.createdAt, row.createdAt].filter((t): t is string => t !== undefined).sort().at(-1);

The person's newest-app rule has no test. Add one that fails if this line is removed.

730738 const owner = owners.get(repo.ownerId);
731739 const mark = markOf(owner);
732740 people.set(repo.ownerName, {
@@ -744,6 +752,7 @@ function rank(
744752 apps: (was?.numbers.apps ?? 0) + 1,
745753 },
746754 shippedAt: latest ?? null,
755 ...(newest === undefined ? {} : { createdAt: newest }),
747756 // A person ranks by their best app, so one with many small ones
748757 // does not crowd out everything else.
749758 score: Math.max(was?.score ?? 0, row.score),
@@ -800,6 +809,7 @@ function sortKey(r: ExploreRow, sort: ExploreSort): number | string {
800809 case "likes": return r.numbers.likes;
801810 case "use": return r.numbers.awakeHours;
802811 case "fresh": return r.shippedAt === null ? 0 : Date.parse(r.shippedAt) || 0;
812 case "new": return r.createdAt === undefined ? 0 : Date.parse(r.createdAt) || 0;
803813 case "name": return r.name.toLowerCase();
804814 }
805815 }
src/web/studio/explore.ts +1
@@ -206,6 +206,7 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
206206 { label: "Liked", sort: "likes" as const },
207207 { label: "Use", sort: "use" as const },
208208 { label: "Fresh", sort: "fresh" as const },
209 { label: "Newest", sort: "new" as const },
209210 ];
210211 const windows = [
211212 { label: "Any time", updated: "all" as const },
src/web/style/content.ts +2
@@ -176,6 +176,8 @@ a.origin-chip:hover { border-color: var(--border-strong); color: var(--fg); }
176176 /* /explore (#9370): rows wrap rather than truncate a long name or description. */
177177 [data-explore] .row-title, [data-explore] .row-meta { white-space: normal; overflow: visible; }
178178 [data-explore] .row { flex-wrap: wrap; }
179 /* Seven sort words are wider than a phone: wrap them, do not scroll inside the bar. */
180 [data-explore] .bar .seg { flex-wrap: wrap; overflow: visible; }
179181 [data-explore] .row-main { flex: 1 1 14rem; }
180182 /* The forges pages (#9372): a row's trail of badges and buttons drops under its text on a phone and wraps. */
181183 [data-forges] .row-title, [data-forges] .row-meta { white-space: normal; overflow: visible; }
test/explore-parity.test.ts +29 −8
@@ -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);
@@ -95,6 +102,14 @@ function seedSignals(): void {
95102 awake(["pine", "kiln-pine"], 10);
96103 awake(["olive", "garden-olive"], 5);
97104 awake(["birch", "kiln-birch"], 2);
105 // made, newest first: kiln-pine 1h ago, loom-olive 2h, garden-birch 3h; the rest 30 days ago. A
106 // person ranks by their newest app.
107 const made = (r: [string, string], hoursAgo: number) =>
108 app.db.run("UPDATE repo SET created_at = ?1 WHERE id = ?2", [new Date(now - hoursAgo * 3_600_000).toISOString(), repoId(...r)]);
109 for (const row of app.db.query<{ id: string }, []>("SELECT id FROM repo").all()) app.db.run("UPDATE repo SET created_at = ?1 WHERE id = ?2", [new Date(now - 30 * DAY).toISOString(), row.id]);
110 made(["pine", "kiln-pine"], 1);
111 made(["olive", "loom-olive"], 2);
112 made(["birch", "garden-birch"], 3);
98113 // put away: loom-pine is only in archived:yes
99114 app.db.run("UPDATE repo SET archived_at = ?1 WHERE id = ?2", [new Date(now).toISOString(), repoId("pine", "loom-pine")]);
100115 }
@@ -119,7 +134,10 @@ const LINES = [
119134 "forks:0 ships:1 live:yes",
120135 ];
121136
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. */
137 /**
138 * The row links inside the page's `<ul class="list">`, in order: each row's title is the one link
139 * to its own url.
140 */
123141 function pageOrder(html: string): string[] {
124142 const list = /<ul class="list">([\s\S]*?)<\/ul>/.exec(html);
125143 if (list === null) return [];
@@ -139,7 +157,8 @@ async function mcp(line: string): Promise<{ ok: boolean; text: string }> {
139157 }
140158
141159 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.
160 // The orders the seeded signals must give, so a sort that ignores its signal (and falls back to
161 // name) fails.
143162 const EXPECTED: Record<string, string[]> = {
144163 "kind:app sort:forks": ["olive/loom-olive", "olive/garden-olive"],
145164 "kind:app sort:ships": ["pine/garden-pine", "birch/loom-birch"],
@@ -147,6 +166,8 @@ describe("one filter, three surfaces", () => {
147166 "kind:app sort:use": ["pine/kiln-pine", "olive/garden-olive", "birch/kiln-birch"],
148167 "kind:app sort:fresh": ["birch/loom-birch", "pine/garden-pine", "olive/kiln-olive"],
149168 "kind:app sort:name": ["birch/garden-birch", "birch/kiln-birch", "birch/loom-birch", "olive/garden-olive", "olive/kiln-olive", "olive/loom-olive", "pine/garden-pine", "pine/kiln-pine"],
169 "kind:app sort:new": ["pine/kiln-pine", "olive/loom-olive", "birch/garden-birch"],
170 "kind:person sort:new": ["pine", "olive", "birch"],
150171 "kind:person sort:forks": ["olive"],
151172 "kind:app updated:7d": ["pine/garden-pine", "birch/loom-birch"],
152173 "kind:app archived:yes sort:name": ["birch/garden-birch", "birch/kiln-birch", "birch/loom-birch", "olive/garden-olive", "olive/kiln-olive", "olive/loom-olive", "pine/garden-pine", "pine/kiln-pine", "pine/loom-pine"],
@@ -247,13 +268,13 @@ describe("one filter, three surfaces", () => {
247268 expect(api.status).toBe(400);
248269 const body = (await api.json()) as { error: string; message: string };
249270 expect(body.error).toBe("unknown_filter");
250 expect(body.message).toContain("use score, forks, ships, likes, use, fresh, name");
271 expect(body.message).toContain("use score, forks, ships, likes, use, fresh, new, name");
251272 const tool = await mcp("sort:bogus");
252273 expect(tool.ok).toBe(false);
253 expect(tool.text).toContain("use score, forks, ships, likes, use, fresh, name");
274 expect(tool.text).toContain("use score, forks, ships, likes, use, fresh, new, name");
254275 const page = await fetch(`${servers.url}/explore?q=${q}`);
255276 expect(page.status).toBe(200);
256 expect(await page.text()).toContain("use score, forks, ships, likes, use, fresh, name");
277 expect(await page.text()).toContain("use score, forks, ships, likes, use, fresh, new, name");
257278 for (const bad of ["kind:x", "updated:2y", "archived:maybe"]) {
258279 expect((await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent(bad)}`)).status).toBe(400);
259280 }
test/explore-sort.test.ts +39
@@ -16,9 +16,11 @@ import { promote } from "./helpers/members.ts";
1616 quietLogs();
1717 const DAY = 86_400_000;
1818 const HOUR = 3_600_000;
19 const DEFAULT_ORDER = ["/olive/loom", "/olive/garden", "/olive/kiln", "/olive/zed"];
1920 let dir: string;
2021 let app: App;
2122 let servers: Servers;
23 let olive: Awaited<ReturnType<typeof createUser>> extends infer R ? R extends { ok: true; value: infer V } ? V : never : never;
2224
2325 // newest ships: kiln (1 day), garden (10), loom (20). most used: loom (200 h), garden (50), kiln
2426 // (1).
@@ -28,6 +30,7 @@ beforeAll(async () => {
2830 const made = await createUser(app.db, { origin: "seed", username: "olive", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: false });
2931 if (!made.ok) throw new Error(made.error);
3032 proveAll(app);
33 olive = made.value;
3134 promote(app.db, made.value);
3235 const now = Date.now();
3336 for (const [name, shipDays, hours] of [["garden", 10, 50], ["kiln", 1, 1], ["loom", 20, 200]] as const) {
@@ -94,3 +97,39 @@ test("an unknown sort falls back to the default with a note, never a 500", async
9497 expect(bad.html).toContain("is not a sort");
9598 expect(bad.html).not.toMatch(/aria-current="[^"]+"[^>]*>\s*Fresh\s*</);
9699 });
100
101 test("sort=new puts the most recently made app first, and its link is marked", async () => {
102 // Make `zed` last, so it is newest though it never shipped.
103 const repo = await createRepo(app, olive, { name: "zed", visibility: "public" });
104 if (!repo.ok) throw new Error(String(repo.error));
105 insertApp(app.db, { repoId: repo.value.id, slug: "olive-zed", access: "public" });
106 app.db.query("UPDATE repo SET created_at = ?1 WHERE id = ?2").run(new Date(Date.now() + HOUR).toISOString(), repo.value.id);
107 const res = await get("?kind=app&sort=new");
108 expect(listed(res.html)[0]).toBe("/olive/zed");
109 expect(res.html).toMatch(/<a[^>]*aria-current="[^"]+"[^>]*>\s*Newest\s*<\/a>/);
110 // Without a sort, the order is the score's, and zed (no ships, no use) is last.
111 expect(listed((await get("?kind=app")).html)).toEqual(DEFAULT_ORDER);
112 });
outdated

Weak: this passes for any order that does not start with zed. Assert the exact default order. Also add a person-sort assertion for the newest-app rule.

113
114 test("sort=new ranks a person by their newest app, not by the order of their apps", async () => {
115 const amber = await createUser(app.db, { origin: "seed", username: "amber", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: false });
116 if (!amber.ok) throw new Error(amber.error);
117 proveAll(app);
118 promote(app.db, amber.value);
119 // One app far older than anything, one newer than olive's newest (zed, +1 h).
120 for (const [name, at] of [["relic", -10 * DAY], ["fresh", 3 * HOUR]] as const) {
121 const repo = await createRepo(app, amber.value, { name, visibility: "public" });
122 if (!repo.ok) throw new Error(String(repo.error));
123 insertApp(app.db, { repoId: repo.value.id, slug: `amber-${name}`, access: "public" });
124 app.db.query("UPDATE repo SET created_at = ?1 WHERE id = ?2").run(new Date(Date.now() + at).toISOString(), repo.value.id);
125 }
126 const res = await get("?kind=person&sort=new");
127 expect(listed(res.html).slice(0, 2)).toEqual(["/amber", "/olive"]);
128 });
129
130 test("sort=forks is accepted and marked, and the kind links keep it", async () => {
131 const res = await get("?kind=app&sort=forks");
132 expect(res.status).toBe(200);
133 expect(res.html).toMatch(/<a[^>]*aria-current="[^"]+"[^>]*>\s*Forks\s*<\/a>/);
134 expect(link(res.html, "People")).toContain("sort=forks");
135 });
test/explore-unknown-words.test.ts +3 −3
@@ -82,7 +82,7 @@ describe("readExploreLine", () => {
8282 });
8383
8484 test("the note names what is taken", () => {
85 expect(exploreNote(["sort:bogus"])).toBe("sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, name");
85 expect(exploreNote(["sort:bogus"])).toBe("sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, new, name");
8686 expect(exploreNote(["kind:x"])).toBe("kind:x is not a kind — use app, person, forge");
8787 });
8888 });
@@ -106,7 +106,7 @@ describe("the page and the API", () => {
106106 const q = encodeURIComponent("sort:bogus garden");
107107 const out = await (await fetch(`${servers.url}/explore?q=${q}`)).text();
108108 expect(out.split("is not a sort").length).toBe(2);
109 expect(out).toContain("sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, name");
109 expect(out).toContain("sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, new, name");
110110 expect(out).not.toContain(encodeURIComponent("sort:bogus"));
111111 expect(out).toContain(`href="${linkOf("kind:app garden")}"`);
112112 });
@@ -160,7 +160,7 @@ describe("the page and the API", () => {
160160 };
161161 const sort = await call("sort:bogus");
162162 expect(sort.isError).toBe(true);
163 expect(sort.text).toContain("unknown_filter: sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, name");
163 expect(sort.text).toContain("unknown_filter: sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, new, name");
164164 const fine = await call("sort:forks");
165165 expect(fine.isError).toBe(false);
166166 expect(JSON.parse(fine.text)).toHaveProperty("items");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs