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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13334-the-404-page-offers-the-three-most-likel → main 4 commits fork 5 threads · 5 unresolved
docs/features/README.md +1
| @@ -54,6 +54,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md). | ||
| 54 | 54 | - [](cmd-k-repositories.md) |
| 55 | 55 | - [](go-jumps.md) |
| 56 | 56 | - [](hotkey-hints.md) |
| 57 | - [](near-pages.md) | |
| 57 | 58 | - [](decision-keys.md) |
| 58 | 59 | - [](page-help.md) |
| 59 | 60 | - [](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 @@ | ||
| 8 | 8 | * to see something the web would have hidden. |
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | import { nearPages } from "../web/near_pages.ts"; | |
| 11 | 12 | import type { App as Forge } from "../app.ts"; |
| 12 | 13 | import { search } from "../actions/search.ts"; |
| 13 | 14 | import { greppable } from "../core/search.ts"; |
| @@ -310,8 +311,14 @@ export function forgeCommands(session: Session): (ctx: Ctx) => Command[] { | ||
| 310 | 311 | // this check the palette would be a way around `canRead`. |
| 311 | 312 | if (!repo || !canRead(session.db, repo, session.user)) { |
| 312 | 313 | 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); | |
| 313 | 318 | 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(", ")}` | |
| 315 | 322 | : `not found — did you mean ${near.map((r) => `${r.ownerName}/${r.name}`).join(", ")}?`; |
| 316 | 323 | } |
| 317 | 324 | // 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"; | ||
| 28 | 28 | import { keptBehind } from "../core/following.ts"; |
| 29 | 29 | import { html, raw, when, type Html } from "./html.ts"; |
| 30 | 30 | import { icon } from "./icons.ts"; |
| 31 | import { nearPages } from "./near_pages.ts"; | |
| 31 | 32 | import { page, redirect } from "./layout.ts"; |
| 32 | 33 | import { |
| 33 | 34 | browseActions, |
| @@ -82,12 +83,17 @@ export function notFoundPage(ctx: Ctx, opts: { plain?: boolean } = {}): Response | ||
| 82 | 83 | ? btn("Search", { href: "/search" }) |
| 83 | 84 | : html``; |
| 84 | 85 | 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 | ]; | |
| 85 | 93 | const didYouMean = |
| 86 | near.length === 0 | |
| 94 | tries.length === 0 | |
| 87 | 95 | ? 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>`; | |
| 91 | 97 | 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. |
||
| 92 | 98 | { |
| 93 | 99 | ctx, |
| @@ -210,7 +216,10 @@ export interface RepoHeaderOptions { | ||
| 210 | 216 | * the repo name steps down to a plain element. Exactly one h1 per document. |
| 211 | 217 | */ |
| 212 | 218 | 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 | */ | |
| 214 | 223 | quiet?: boolean; |
| 215 | 224 | } |
| 216 | 225 |
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 | ||
| 259 | 259 | expect(cleared).not.toContain("Esc clears"); |
| 260 | 260 | expect(cleared).not.toContain("sort:forks"); |
| 261 | 261 | }); |
| 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 | }); |
Terminal hint has no test. Add one that fails without it (near typo offers a page; guest is not offered an admin page).