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

/search and `GET /api/v1/search` find guides too, as their own group above issues and code #13926

Merged opened this

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

Merged

scout/forge:scout/13889-search-and-get-api-v1-search-find-guides → main 7 commits fork 6 threads · 6 unresolved

  • Merged. scout/13889-search-and-get-api-v1-search-find-guides was merged into main as 71a7d72.

Review

Sign in to review this change.
14 files changed +210 −22
docs/design/attention-budget.json +5 −5
@@ -137,16 +137,16 @@
137137 },
138138 "search results": {
139139 "390": {
140 "words": 58,
141 "blocks": 5,
140 "words": 98,
outdated

A rise from 58 to 246 words is more than four times the first-view budget of this page (principles 1 and 3). Trim the snippets or the group to land nearer the old figure, or state why it must be this large.

141 "blocks": 13,
142142 "colours": 1
143143 },
144144 "1280": {
145 "words": 58,
146 "blocks": 5,
145 "words": 98,
146 "blocks": 13,
147147 "colours": 1
148148 },
149 "note": "/search?q=forge, signed in as an admin."
149 "note": "Raised from 58 words and 5 blocks for the Guides group (#13889): two guide rows, each a title and a 60-character snippet, only when a guide matches; the API and the terminal carry five."
150150 },
151151 "map": {
152152 "390": {
docs/features/README.md +1
@@ -80,6 +80,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
8080 - [Page help (`? Help`)](page-help.md)
8181 - [Palette rows: numbers, people, settings, actions](palette-rows.md)
8282 - [Phone search is the palette](search-is-palette.md)
83 - [Search finds guides](search-finds-guides.md)
8384 - [Pick list](pick-list.md)
8485 - [The empty palette lists what you opened last](palette-recent.md)
8586
docs/features/search-finds-guides.md added +11
@@ -0,0 +1,11 @@
1 # Search finds guides
2
3 `/search?q=fork` shows a **Guides** group: up to five guide pages whose title
4 or text holds the query, each with its path and a snippet. When a guide's title
5 holds every word asked, Guides leads the page; otherwise it follows
6 repositories.
7
8 The same group comes back from `GET /api/v1/search` (`docs`, all five) and the
9 MCP `search` tool. The page shows the first two with a short snippet, to keep
outdated

Both doors: this sentence admits the terminal's search does not show guides. Build the terminal side in src/tui/ and document it here.

10 the first view small. The terminal's palette (`ctrl+p`) has a **Guides**
11 section above Code: Enter reads the guide in the docs screen.
src/actions/search.ts +13 −1
@@ -31,11 +31,14 @@ import {
3131 type IssueHit,
3232 type RepoHit,
3333 type CodeHit,
34 type DocsHit,
35 MAX_DOC_HITS,
3436 type SearchKind,
3537 type SearchResults,
3638 } from "../core/search.ts";
3739 import type { Repo } from "../core/repos.ts";
3840 import type { User } from "../core/users.ts";
41 import { searchDocs } from "../view/docs.ts";
3942 import { providerForOrigin } from "../origins/credential.ts";
4043
4144 /** Default page size for each list. */
@@ -130,6 +133,7 @@ export async function search(
130133 repos: [],
131134 issues: [],
132135 code: [],
136 docs: [],
133137 truncated: { repos: false, issues: false, code: false },
134138 moreCode: false,
135139 codeSkipped: false,
@@ -200,10 +204,18 @@ export async function search(
200204 : { hits: [], truncated: false, more: false, skipped: false };
201205 if (wants("code")) phase("code", performance.now() - codeAt);
202206
207 // Guides are public and live in the one built index /docs reads: no file is
208 // read per request. A search scoped to one repository has no guides.
209 const docs: DocsHit[] =
210 kind === "all" && input.repo === undefined
211 ? searchDocs(q, MAX_DOC_HITS).map((h) => ({ title: h.title, path: `/docs/${h.name}`, snippet: h.snippet }))
212 : [];
213
203214 return {
204215 repos,
205216 issues,
206217 code: code.hits,
218 docs,
207219 truncated: {
208220 repos: repos.length >= limit,
209221 issues: localIssueCount >= limit,
@@ -308,5 +320,5 @@ export async function searchWithin(
308320 const ms = spent[name];
309321 if (ms !== undefined) input.phase?.(name, ms);
310322 }
311 return { ...hits, truncated, moreCode, codeSkipped };
323 return { ...hits, docs: [], truncated, moreCode, codeSkipped };
312324 }
src/contract/openapi/routes/getApiV1Search.ts +1 −1
@@ -1,4 +1,4 @@
11 import { type Route, limitTo } from "../shared.ts";
22 import { SEARCH_LIMIT_MAX } from "../../../actions/search.ts";
33
4 export const route: Route = { method: "get", path: "/api/v1/search", summary: "Search issues, pulls, repositories and code; `kind` narrows it", auth: false, role: "anonymous", query: { q: "string", kind: "string", limit: limitTo(SEARCH_LIMIT_MAX) }, refusals: { invalid_kind: "kind is not all, repos, issues or code (422)", invalid_limit: "limit is not a whole number from 1 to 100 (422)" }, reply: { repos: "array", issues: "array", code: "array", truncated: "object", moreCode: "boolean", codeSkipped: "boolean", note: "string, only when q is blank: what to send" } };
4 export const route: Route = { method: "get", path: "/api/v1/search", summary: "Search guides, issues, pulls, repositories and code; `kind` narrows it", auth: false, role: "anonymous", query: { q: "string", kind: "string", limit: limitTo(SEARCH_LIMIT_MAX) }, refusals: { invalid_kind: "kind is not all, repos, issues or code (422)", invalid_limit: "limit is not a whole number from 1 to 100 (422)" }, reply: { repos: "array", issues: "array", code: "array", docs: "array of { title, path, snippet }, at most 5, guides matching; only for kind all", truncated: "object", moreCode: "boolean", codeSkipped: "boolean", note: "string, only when q is blank: what to send" } };
src/core/search.ts +11
@@ -155,10 +155,21 @@ export interface CodeHit {
155155 readonly text: string;
156156 }
157157
158 /** A guide that matched: its title, where to read it and a line around the match. */
159 export interface DocsHit {
160 readonly title: string;
161 readonly path: string;
162 readonly snippet: string;
163 }
164
165 export const MAX_DOC_HITS = 5;
166
158167 export interface SearchResults {
159168 readonly repos: readonly RepoHit[];
160169 readonly issues: readonly IssueHit[];
161170 readonly code: readonly CodeHit[];
171 /** Guides matching, from the index /docs uses: at most `MAX_DOC_HITS`; only for kind `all`. */
172 readonly docs: readonly DocsHit[];
162173 /** Which lists hit their ceiling — a client can say "and more". */
163174 readonly truncated: {
164175 readonly repos: boolean;
src/http/mcp/tools/search.ts +1 −1
@@ -3,7 +3,7 @@ import { searchRun } from "../reads.ts";
33
44 export const tool: Tool = {
55 name: "search",
6 doc: "`{ q, kind?, limit?, repo?, all? }`: issues, pulls, repositories and code you can read, the same results as /search, drawn as the `ui://forge/search` card; `repo` keeps to one; `moreCode` says the code grep stopped at its budget, `all` greps the rest",
6 doc: "`{ q, kind?, limit?, repo?, all? }`: guides (`docs`, kind all), issues, pulls, repositories and code you can read, the same results as /search, drawn as the `ui://forge/search` card; `repo` keeps to one; `moreCode` says the code grep stopped at its budget, `all` greps the rest",
77 description:
88 "Find issues, pulls, repositories and code you can read; `kind` and `repo` narrow.",
99 inputSchema: {
src/tui/app/palette.ts +9 −3
@@ -173,12 +173,14 @@ export class Palette {
173173
174174 /**
175175 * Everything drawable, headings included, in section order: search results
176 * first (they answer the question that was typed), commands last.
176 * first (they answer the question that was typed), commands last. Guides
177 * are the exception: they follow the commands, so a word that is both a
178 * verb and a guide's title ("Queue") still puts the verb under Enter.
177179 */
178180 rows(): Row[] {
179181 const out: Row[] = [];
180182 let section = "";
181 for (const item of this.results) {
183 const push = (item: PaletteItem): void => {
182184 if (item.section !== section) {
183185 section = item.section;
184186 out.push({ kind: "header", label: section });
@@ -189,7 +191,9 @@ export class Palette {
189191 indices: item.indices ?? [],
190192 mark: item.mark ?? "",
191193 });
192 }
194 };
195 const guides = this.results.filter((i) => i.section === "Guides");
196 for (const item of this.results) if (item.section !== "Guides") push(item);
193197 const verbs = this.matches();
194198 if (verbs.length > 0) {
195199 if (out.length > 0) out.push({ kind: "header", label: "Commands" });
@@ -201,6 +205,8 @@ export class Palette {
201205 mark: "",
202206 });
203207 }
208 section = "";
209 for (const item of guides) push(item);
204210 return out;
205211 }
206212
src/tui/forge.ts +16 −1
@@ -103,7 +103,8 @@ import { noteRead, telemetryReader } from "../actions/telemetry.ts";
103103 import { queuesFor, systemFor } from "../system/telemetry.ts";
104104 import { apiScreen } from "./screens/api.ts";
105105 import { changelogScreen } from "./screens/changelog.ts";
106 import { docsScreen } from "./screens/docs.ts";
106 import { docScreen, docsScreen } from "./screens/docs.ts";
107 import { anyDocEntry } from "../view/docs.ts";
107108 import { keeperScreen } from "./screens/keeper.ts";
108109 import { releasesScreen } from "./screens/releases.ts";
109110 import { mayRead } from "../release/gate.ts";
@@ -856,6 +857,20 @@ export function forgeSearch(session: Session): (ctx: Ctx) => PaletteSearch {
856857 });
857858 }
858859
860 // Guides: public, from the index /docs reads; Enter reads the guide.
861 for (const hit of found.docs) {
862 const entry = anyDocEntry(hit.path.replace(/^\/docs\//, ""));
863 if (entry === undefined) continue;
864 items.push({
865 id: `doc:${entry.name}`,
866 section: "Guides",
867 mark: mark("file", G.dot),
868 title: hit.title,
869 hint: hit.snippet.slice(0, 60),
870 run: () => ctx.push(docScreen(ctx, entry, sshOn(session.app.db))),
871 });
872 }
873
859874 for (const hit of found.code) {
860875 const where = `${hit.repo.owner}/${hit.repo.name}`;
861876 items.push({
src/tui/screens/docs.ts +1 −1
@@ -15,7 +15,7 @@ export function docRows(entries: readonly DocEntry[]): ListRow[] {
1515 return entries.map((e) => ({ title: e.title }));
1616 }
1717
18 function docScreen(ctx: Ctx, entry: DocEntry, ssh: boolean): Screen {
18 export function docScreen(ctx: Ctx, entry: DocEntry, ssh: boolean): Screen {
1919 const scroll = new Scroll();
2020 let cache: { w: number; lines: ReturnType<typeof renderMarkdown> } | undefined;
2121 const text = docText(entry, ssh);
src/web/pages/search.ts +31 −8
@@ -31,6 +31,7 @@ import {
3131 greppable,
3232 searchKind,
3333 type CodeHit,
34 type DocsHit,
3435 type IssueHit,
3536 type RepoHit,
3637 type SearchKind,
@@ -300,6 +301,25 @@ function searchHref(
300301 return `/search?${params.toString()}`;
301302 }
302303
304 /** Whether a guide's title holds every word asked: then guides lead the page. */
305 export function guideTitleMatches(query: string, docs: readonly DocsHit[]): boolean {
306 const words = query.toLowerCase().split(/\s+/).filter((w) => w !== "");
307 return words.length > 0 && docs.some((d) => words.every((w) => d.title.toLowerCase().includes(w)));
308 }
309
310 /** Guide rows shown on the page; the API and the terminal carry all five. */
311 const PAGE_GUIDES = 2;
312 /** A snippet the page shows: enough to tell the guides apart, no more. */
outdated

Dead parameter: void a; only silences the lint. Remove a from docsSection. (Clean)

313 const PAGE_SNIPPET = 60;
314
315 /** The guides group: a heading over rows linking to /docs, no new class. */
outdated

Principles 2/7: guide rows reuse icon("repo"), which reads as a repository. Use a guide/doc icon, and drop the count in the h2 (principle 1: nothing says things twice).

316 function docsSection(docs: readonly DocsHit[]): Html {
317 return html`<section id="docs" aria-labelledby="h-docs">
318 <h2 class="mt" id="h-docs">Guides</h2>
319 ${rowsUnderHeading(docs.slice(0, PAGE_GUIDES).map((d) => row({ href: d.path, nav: true, lead: icon("file"), title: d.title, meta: html`${d.snippet.slice(0, PAGE_SNIPPET)}` })))}
320 </section>`;
321 }
322
303323 function section(
304324 a: Asked,
305325 [kind, , title, emptyText]: Words,
@@ -513,7 +533,16 @@ export async function searchPage(ctx: Ctx): Promise<Response> {
513533
514534 const nothing =
515535 a.kind === "all" &&
516 found.repos.length + found.issues.length + found.code.length === 0;
536 found.repos.length + found.issues.length + found.code.length + found.docs.length === 0;
537 const guides = found.docs.length === 0 ? null : docsSection(found.docs);
538 const guidesFirst = guideTitleMatches(a.query, found.docs);
539 const sections = WORDS
540 .filter(([kind]) => kind !== "all" && (a.kind === "all" || a.kind === kind))
541 .map((w) => ({ kind: w[0], html: section(a, w, ...rows[w[0]](), w[0] === "code" ? moreCode : null) }));
542 const ordered = [
543 ...(guidesFirst ? [guides] : []),
544 ...sections.flatMap((s) => (s.kind === "repos" && !guidesFirst ? [s.html, guides] : [s.html])),
545 ];
517546 const body = html`<div data-search>${pageHead(html`Results for “${echoed(a.query)}”`)} ${form}${trimmed}
518547 <div class="bar mb">${chips}</div>
519548 ${liveToggle}
@@ -550,13 +579,7 @@ export async function searchPage(ctx: Ctx): Promise<Response> {
550579 )} or <a href="/?${new URLSearchParams({ text: a.query }).toString()}" data-tell>tell the crew</a>`,
551580 )}
552581 </p>`
553 : WORDS
554 .filter(
555 ([kind]) => kind !== "all" && (a.kind === "all" || a.kind === kind),
556 )
557 .map((w) =>
558 section(a, w, ...rows[w[0]](), w[0] === "code" ? moreCode : null),
559 )}</div>`;
582 : ordered}</div>`;
560583 const response = page({ ctx, title: `Search · ${echoed(a.query)}`, body, styleCss: SEARCH_CSS });
561584 notePhase(ctx.request, "render", performance.now() - rendering);
562585 return response;
test/search-docs.test.ts added +107
@@ -0,0 +1,107 @@
1 /** Search finds guides as their own `docs` group, from the index /docs reads (#13889). */
2 import { afterAll, beforeAll, expect, spyOn, test } from "bun:test";
3 import * as fs from "node:fs";
4 import { expectWork } from "./helpers/work.ts";
5 import { mkdtemp, rm } from "node:fs/promises";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { createApp } from "../src/app.ts";
9 import { search } from "../src/actions/search.ts";
10 import { guideTitleMatches } from "../src/web/pages/search.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { searchDocs } from "../src/view/docs.ts";
13 import { forgeSearch } from "../src/tui/forge.ts";
14 import { Session } from "../src/tui/session.ts";
15 import type { Ctx } from "../src/tui/app/app.ts";
16
17 let dir = "";
18 let app: ReturnType<typeof createApp>;
19 let servers: Servers;
20
21 beforeAll(async () => {
22 dir = await mkdtemp(join(tmpdir(), "forge-search-docs-"));
23 app = createApp({ dataDir: dir, port: 0 });
24 servers = await serve(app);
25 });
26 afterAll(async () => {
27 servers.stop();
28 await rm(dir, { recursive: true, force: true });
29 });
30
31 test("a guide is found by a title word, with title, path and snippet, at most 5", async () => {
32 const found = await search(app, undefined, { q: "fork" });
33 expect(found.docs.length).toBeGreaterThan(0);
34 expect(found.docs.length).toBeLessThanOrEqual(5);
35 const first = found.docs[0]!;
36 expect(first.path).toMatch(/^\/docs\/.+\.md$/);
37 expect(first.title).not.toBe("");
38 expect(first.snippet).not.toBe("");
39 });
40
41 test("a guide is found by a body word that is in no title", async () => {
outdated

word ?? "fork" makes this test pass even when no body word is found, so it would not fail without the behaviour. Pick a fixed body-only word and assert the specific guide is returned. Also add a test that guides follow repositories when no title matches.

42 // "ulid" is in the body of the feed-cursor note and in no title.
43 const found = await search(app, undefined, { q: "ulid" });
44 const hit = found.docs.find((d) => d.path === "/docs/features/feed-cursor.md");
45 expect(hit).toBeDefined();
46 expect(hit!.title.toLowerCase()).not.toContain("ulid");
47 expect(hit!.snippet.toLowerCase()).toContain("ulid");
48 });
49
50 test("guides follow repositories when no title holds the query, and lead when one does", async () => {
51 const body = await (await fetch(`${servers.url}/search?q=ulid`)).text();
52 expect(body).toContain('id="docs"');
53 expect(body.indexOf('id="repos"')).toBeLessThan(body.indexOf('id="docs"'));
54 const lead = await (await fetch(`${servers.url}/search?q=fork`)).text();
55 expect(lead.indexOf('id="docs"')).toBeLessThan(lead.indexOf('id="repos"'));
56 });
57
58 test("the page shows two guides and no count; the index is built once and a search reads no file", async () => {
59 const page = await (await fetch(`${servers.url}/search?q=fork`)).text();
60 const docs = page.slice(page.indexOf('id="docs"'), page.indexOf('id="repos"'));
61 expect(docs.match(/href="\/docs\//g)?.length).toBe(2);
62 expect(docs).toMatch(/<h2[^>]*>Guides<\/h2>/);
63 searchDocs("fork", 5); // warm
64 const reads = spyOn(fs, "readFileSync");
65 try {
66 for (let i = 0; i < 10; i++) await search(app, undefined, { q: "fork" });
67 expectWork(reads.mock.calls.filter((c) => String(c[0]).includes("/docs/")).length, { max: 0 });
68 } finally {
69 reads.mockRestore();
70 }
71 });
72
73 test("an empty q answers as before, with an empty docs group; kind repos has none", async () => {
74 const empty = await search(app, undefined, { q: " " });
75 expect(empty.docs).toEqual([]);
76 expect(empty.repos).toEqual([]);
77 expect((await search(app, undefined, { q: "fork", kind: "repos" })).docs).toEqual([]);
78 });
79
80 test("the API and the page carry the group; guides lead when a title matches", async () => {
81 const api = (await (await fetch(`${servers.url}/api/v1/search?q=fork`)).json()) as { docs: { title: string }[] };
82 expect(api.docs.length).toBeGreaterThan(0);
83 const page = await (await fetch(`${servers.url}/search?q=fork`)).text();
84 expect(page).toContain('id="docs"');
85 expect(page.indexOf('id="docs"')).toBeLessThan(page.indexOf('id="repos"'));
86 const body = await (await fetch(`${servers.url}/search?q=zzzqqqxx`)).text();
87 expect(body).not.toContain('id="docs"');
88 });
89
90 test("guideTitleMatches wants every word in a title", () => {
91 const docs = [{ title: "Forking an app", path: "/docs/x.md", snippet: "" }];
92 expect(guideTitleMatches("fork", docs)).toBe(true);
93 expect(guideTitleMatches("fork zebra", docs)).toBe(false);
94 expect(guideTitleMatches("", docs)).toBe(false);
95 });
96
97 test("the terminal's palette search has a Guides section; Enter opens the guide", async () => {
98 const guest = new Session(app, { sshUsername: "anyone", remoteAddress: "198.51.100.7", fingerprint: "SHA256:none" });
99 const pushed: { title: string }[] = [];
100 const ctx = { icons: "plain", toast: () => {}, push: (s: { title: string }) => pushed.push(s), invalidate: () => {} } as unknown as Ctx;
101 const items = await forgeSearch(guest)(ctx)("ulid", false, new AbortController().signal);
102 const guide = items.find((i) => i.id === "doc:features/feed-cursor.md");
103 expect(guide?.section).toBe("Guides");
104 guide!.run();
105 expect(pushed.length).toBe(1);
106 expect(pushed[0]!.title).not.toBe("");
107 });
test/search.test.ts +2
@@ -32,6 +32,7 @@ interface Results {
3232 note?: string;
3333 moreCode?: boolean;
3434 codeSkipped?: boolean;
35 docs?: { title: string; path: string; snippet: string }[];
3536 repos: (
3637 | {
3738 source: "local";
@@ -396,6 +397,7 @@ describe("search: one query, four sources", () => {
396397 expect({ ...results, note: undefined }).toEqual({
397398 note: undefined,
398399 repos: [],
400 docs: [],
399401 issues: [],
400402 code: [],
401403 moreCode: false,
test/suspended-hidden.test.ts +1 −1
@@ -90,7 +90,7 @@ describe("a suspended account's repositories leave every list", () => {
9090 };
9191 await look("explore", "/explore");
9292 await look("search page", "/search?q=tools");
93 await look("search api", "/api/v1/search?q=tools", "tools");
93 await look("search api", "/api/v1/search?q=tools&kind=repos", "tools");
9494 await look("repo list api", "/api/v1/repos", "tools");
9595 await look("owner page", "/sam", "tools");
9696 await look("owner api", "/api/v1/users/sam", '"sam"');

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs