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

The 404 page offers the three most likely pages by edit distance to the path asked #13351

Merged opened this

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

Merged

scout/forge:scout/13334-the-404-page-offers-the-three-most-likel → main 4 commits fork 5 threads · 5 unresolved

  • Merged. scout/13334-the-404-page-offers-the-three-most-likel was merged into main as 620d275.

Review

Sign in to review this change.
7 files changed +183 −6
docs/features/README.md +1
@@ -54,6 +54,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
5454 - [Cmd-K: repositories and their apps](cmd-k-repositories.md)
5555 - [`g` then a letter: jump between pages](go-jumps.md)
5656 - [Hotkey hints](hotkey-hints.md)
57 - [The 404 offers the pages nearest the path asked](near-pages.md)
5758 - [Lists that ask for a decision answer the same keys](decision-keys.md)
5859 - [Page help (`? Help`)](page-help.md)
5960 - [Palette rows: numbers, people, settings, actions](palette-rows.md)
docs/features/near-pages.md added +12
@@ -0,0 +1,12 @@
1 # The 404 offers the pages nearest the path asked
2
3 A mistyped link finds its way in one tap. When a page is not found, the 404
4 adds one line, "Try …", with up to three of the forge's top-level pages whose
5 name is within edit distance 3 of the path's first segment (never more than
6 half the name's length, so `/ab` offers nothing), then any repositories near
7 the address. The pages come from one table, `GO_PAGES` in `src/web/go_pages.ts`,
8 narrowed to what the viewer may open; `src/web/near_pages.ts` ranks them.
9
10 In the terminal, asking the palette for a repository that is not there answers
11 "not found — pages like it, on the web: /explore" when no repository is near
12 but a page is.
src/tui/forge.ts +8 −1
@@ -8,6 +8,7 @@
88 * to see something the web would have hidden.
99 */
1010
11 import { nearPages } from "../web/near_pages.ts";
1112 import type { App as Forge } from "../app.ts";
1213 import { search } from "../actions/search.ts";
1314 import { greppable } from "../core/search.ts";
@@ -310,8 +311,14 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] {
310311 // this check the palette would be a way around `canRead`.
311312 if (!repo || !canRead(session.db, repo, session.user)) {
312313 const near = owner && name ? nearRepos(session.db, session.user, owner, name) : [];
314 const pages = nearPages(`/${spec}`, {
315 signedIn: session.signedIn,
316 admin: session.user?.isAdmin === true,
317 }).map((p) => p.href);
313318 return near.length === 0
314 ? "not found"
319 ? pages.length === 0
320 ? "not found"
321 : `not found — pages like it, on the web: ${pages.join(", ")}`

Terminal hint has no test. Add one that fails without it (near typo offers a page; guest is not offered an admin page).

315322 : `not found — did you mean ${near.map((r) => `${r.ownerName}/${r.name}`).join(", ")}?`;
316323 }
317324 // After the prompt has popped itself, or the pop takes the
src/web/chrome.ts +14 −5
@@ -28,6 +28,7 @@ import { forkFollowMode } from "../core/fork_follow.ts";
2828 import { keptBehind } from "../core/following.ts";
2929 import { html, raw, when, type Html } from "./html.ts";
3030 import { icon } from "./icons.ts";
31 import { nearPages } from "./near_pages.ts";
3132 import { page, redirect } from "./layout.ts";
3233 import {
3334 browseActions,
@@ -82,12 +83,17 @@ export function notFoundPage(ctx: Ctx, opts: { plain?: boolean } = {}): Response
8283 ? btn("Search", { href: "/search" })
8384 : html``;
8485 const near = get ? nearTo(ctx.app.db, ctx.auth.user, ctx.params.owner ?? "", ctx.params.name ?? "") : [];
86 const pages = get
87 ? nearPages(ctx.url.pathname, { signedIn: ctx.auth.user !== undefined, admin: ctx.auth.user?.isAdmin === true })
88 : [];
89 const tries = [
90 ...pages.map((p) => html`<a href="${p.href}">${p.name}</a>`),
91 ...near.map((r) => html`<a href="${repoBase(r)}">${r.ownerName}/${r.name}</a>`),
92 ];
8593 const didYouMean =
86 near.length === 0
94 tries.length === 0
8795 ? html``
88 : html`<p class="muted">Did you mean ${near.map(
89 (r, i) => html`${i > 0 ? ", " : ""}<a href="${repoBase(r)}">${r.ownerName}/${r.name}</a>`,
90 )}?</p>`;
96 : html`<p class="muted">Try ${tries.map((t, i) => html`${i > 0 ? ", " : ""}${t}`)}</p>`;
9197 return page(
outdated

Principle 1: two lines of hints (Pages like it, then Did you mean) say the same thing twice. Merge them into one line when both exist, or show pages first and drop the label to Try.

9298 {
9399 ctx,
@@ -210,7 +216,10 @@ export interface RepoHeaderOptions {
210216 * the repo name steps down to a plain element. Exactly one h1 per document.
211217 */
212218 ownTitle?: boolean;
213 /** Leave the where strip to the repository's home (#8773): a page about one change shows less at rest. */
219 /**
220 * Leave the where strip to the repository's home (#8773): a page about one change shows less at
221 * rest.
222 */
214223 quiet?: boolean;
215224 }
216225
src/web/near_pages.ts added +40
@@ -0,0 +1,40 @@
1 /**

Both doors: this module needs a terminal counterpart in src/tui/ and a docs/features/<name>.md row; none is in the diff.

2 * The top-level pages closest to a path that missed, by edit distance: what
3 * the 404 offers so a mistyped link finds its way in one tap. The candidates
4 * are `GO_PAGES`, the one table of the forge's pages, narrowed to what this
5 * viewer may be sent to, so a page they cannot open is never named.
6 */
7 import { editDistance } from "../text/edit_distance.ts";
8 import { goPagesFor, type GoPage } from "./go_pages.ts";
9
10 const NEAR_MAX = 3;
11 /**
12 * A name is never matched across more than half its own length, so a short path matches nothing by
13 * chance.
14 */
15 const allowed = (asked: string): number => Math.min(NEAR_MAX, Math.floor(asked.length / 2));
16 const NEAR_SHOWN = 3;
17 const MAX_ASKED = 40;
18
19 /**
20 * Up to three pages whose name is within edit distance 3 (at most half its length) of the path's
21 * first segment, nearest first.
22 */
outdated

Principle 8 and the phone user: a fixed distance of 3 matches almost any 2-4 letter path (/ab offers Apps). Cap the distance at about half the name length so only real typos are offered, and test it.

23 export function nearPages(pathname: string, viewer: { signedIn: boolean; admin: boolean }): GoPage[] {
24 let first = pathname.split("/").find((s) => s !== "") ?? "";
25 try {
26 first = decodeURIComponent(first);
27 } catch {
28 return [];
29 }
30 first = first.toLowerCase().slice(0, MAX_ASKED);
31 if (first === "") return [];
32 const max = allowed(first);
33 return goPagesFor(viewer)
34 .filter((p) => p.href !== "/")
35 .map((p) => ({ page: p, d: editDistance(first, p.href.slice(1), max) }))
36 .filter((f) => f.d <= max)
37 .sort((x, y) => x.d - y.d)
38 .slice(0, NEAR_SHOWN)
39 .map((f) => f.page);
40 }
test/near-pages.test.ts added +66
@@ -0,0 +1,66 @@
1 /**
2 * The 404 offers the known top-level pages nearest the path asked, and nothing when none is near.
3 */
4 import { afterAll, beforeAll, expect, test } from "bun:test";
5 import { mkdtemp, rm } from "node:fs/promises";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { createApp, type App } from "../src/app.ts";
9 import { serve, type Servers } from "../src/http/server.ts";
10 import { nearPages } from "../src/web/near_pages.ts";
11
12 let dataDir = "";
13 let app: App, servers: Servers;
14
15 beforeAll(async () => {
16 dataDir = await mkdtemp(join(tmpdir(), "forge-nearpages-"));
17 app = createApp({ dataDir, port: 0 });
18 servers = await serve(app);
19 });
20
21 afterAll(async () => {
22 servers.stop();
23 app.close();
24 await rm(dataDir, { recursive: true, force: true });
25 });
26
27 const stranger = { signedIn: false, admin: false };
28
29 test("a near typo finds its page, nearest first, at most three", () => {
30 expect(nearPages("/explroe", stranger)[0]?.href).toBe("/explore");
31 expect(nearPages("/apss", stranger).map((p) => p.href)).toContain("/apps");
32 expect(nearPages("/map", { signedIn: true, admin: false }).length).toBeLessThanOrEqual(3);
33 });
34
35 test("a far path and the root offer nothing", () => {
36 expect(nearPages("/zzzzzzzzzzzzzzzz", stranger)).toEqual([]);
37 expect(nearPages("/", stranger)).toEqual([]);
38 expect(nearPages("/%E0%A4%A", stranger)).toEqual([]);
39 });
40
41 test("a page the viewer may not open is never named", () => {
42 expect(nearPages("/sytem", stranger)).toEqual([]);
43 expect(nearPages("/sytem", { signedIn: true, admin: true }).map((p) => p.href)).toContain("/system");
44 });
45
46 test("the 404 page shows the links, escaped, and a far path shows none", async () => {
47 const near = await (await fetch(`${servers.url}/explroe`)).text();
48 expect(near).toContain('Try');
49 expect(near).toContain('<a href="/explore">Explore</a>');
50 const far = await fetch(`${servers.url}/zzzzzzzzzzzzzzzzzzzz`);
51 expect(far.status).toBe(404);

Stale label: Pages like it is never rendered now, so this cannot fail. Assert not.toContain("Try ") for the far path.

52 expect(await far.text()).not.toContain("Try ");
53 const evil = await (await fetch(`${servers.url}/apps%3Cb%3E`)).text();
54 expect(evil).not.toContain("<b>");
55 });
56
57 test("a short path matches nothing by chance; the cap of three holds", () => {
58 expect(nearPages("/ab", stranger)).toEqual([]);
59 expect(nearPages("/a", stranger)).toEqual([]);
60 expect(nearPages("/apps", stranger).map((p) => p.href)).toContain("/apps");
61 // "/f" style prefixes: a long, loose name near many pages still shows at most three.
62 const admin = { signedIn: true, admin: true };
63 for (const asked of ["/sets", "/boar", "/flo", "/forg", "/audi", "/asks", "/ask"])
64 expect(nearPages(asked, admin).length).toBeLessThanOrEqual(3);
65 expect(nearPages("/boar", admin).length).toBeGreaterThan(1);
66 });
test/tui-dashboard-explore.test.ts +42
@@ -259,3 +259,45 @@ test("a sort alone says Esc clears, and Esc puts the list back in its plain orde
259259 expect(cleared).not.toContain("Esc clears");
260260 expect(cleared).not.toContain("sort:forks");
261261 });
262
263 async function openRepo(spec: string, who: User | null): Promise<string> {
264 const user = who ?? undefined;
265 const terminal = headlessTerminal(200, 32);
266 const { app } = createForgeApp(
267 forge,
268 { sshUsername: user?.username ?? "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user },
269 { terminal, exitHooks: false },
270 );
271 app.start();
272 await settleApp(app);
273 const press = (key: string, ctrl = false): void => app.dispatch({ type: "key", key, ctrl, alt: false, shift: false });
274 press("k", true);
275 await settleApp(app);
276 for (const ch of "Open a repository") press(ch);
277 await settleApp(app);
278 press("enter");
279 await settleApp(app);
280 for (const ch of spec) press(ch);
281 press("enter");
282 await settleApp(app);
283 const text = app.screen.toText();
284 app.stop();
285 return text;
286 }
287
288 test("the palette's repo prompt answers a mistyped page with the page like it", async () => {
289 const text = await openRepo("explroe", null);
290 expect(text).toContain("pages like it, on the web: /explore");
291 });
292
293 test("the palette's repo prompt offers /system to an admin and never to a guest", async () => {
294 forge.db.query("UPDATE user SET is_admin = 1 WHERE id = ?1").run(bob.id);
295 try {
296 expect(await openRepo("sytem", { ...bob, isAdmin: true })).toContain("/system");
297 } finally {
298 forge.db.query("UPDATE user SET is_admin = 0 WHERE id = ?1").run(bob.id);
299 }
300 const guest = await openRepo("sytem", null);
301 expect(guest).toContain("not found");
302 expect(guest).not.toContain("/system");
303 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs