From 1d1205f47179ded2144c66a86113f1359cb8f556 Mon Sep 17 00:00:00 2001 From: bkellam Date: Thu, 20 Nov 2025 16:09:57 -0800 Subject: [PATCH] dev README --- packages/web/src/features/search/README.md | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 packages/web/src/features/search/README.md diff --git a/packages/web/src/features/search/README.md b/packages/web/src/features/search/README.md new file mode 100644 index 00000000..ff34a2e8 --- /dev/null +++ b/packages/web/src/features/search/README.md @@ -0,0 +1,31 @@ +# `/search` + +Code search interface for Sourcebot. + +## Overview + +The search feature parses user queries into an intermediate representation (IR), which is then executed against Zoekt's gRPC search backend. Query parsing uses Lezer for syntax analysis. + +## Architecture + +**Query Flow:** +1. User query string → Lezer parser (via `@sourcebot/query-language`) +2. Lezer syntax tree → Query IR (Zoekt gRPC `Q` proto) +3. Query IR → Zoekt backend → Search results + +## Files + +- **`index.ts`** - Public API exports for the search feature, including search functions and type definitions. + +- **`parser.ts`** - Parses query strings into the query IR using the Lezer parser from `@sourcebot/query-language`. + +- **`ir.ts`** - Defines the `QueryIR` type (internally the Zoekt gRPC `Q` proto) and provides utilities for traversing and querying the IR tree structure. + +- **`types.ts`** - TypeScript types and Zod schemas for search requests, responses, file matches, stats, and streaming results. + +- **`searchApi.ts`** - High-level search API that handles authentication, permission filtering, and orchestrates the query parsing and Zoekt backend calls. + +- **`zoektSearcher.ts`** - Low-level interface to the Zoekt gRPC backend. Handles request construction, streaming search, response transformation, and repository metadata resolution. + +- **`fileSourceApi.ts`** - Retrieves full file contents by executing a specialized search query against Zoekt for a specific file path. +