@core / search

1.0.0 ▾

1.0.0

인증됨MIT

GitHub

Postgres 전문 검색 기반 사이트 검색: 언어별 어간, 접두어 일치, 안전한 스니펫, 오타 대응

코드파일 8개컨텍스트약 511토큰검사 통과

약 511토큰→ src/lib/search/AGENTS.md→ .cursor/rules/genpm-core-search.mdc

이것이 AI가 src/lib/search에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/search — rules for AI agents

Purpose

Site search on Postgres full-text search: one search_documents table fed by any SearchSource (@core/contracts), weighted title/body vectors with the stemmer of each document's language, prefix matching for search-as-you-type, snippets returned as plain parts (never HTML) and, if the pg_trgm extension exists, a typo-tolerant fallback on titles. No external engine, no semantic search.

Map

index.ts — public API: search, registerSearchSource, reindex, indexDocument, removeDocument, reindexJob.
search.ts — indexing and querying. schema.ts — table and GIN index.
adapters/hono.ts — searchRoutes(). adapters/next.ts — searchRoute (GET).

Integration

Generate and apply migrations (see src/lib/db/AGENTS.md). Optional typo tolerance: run create extension if not exists pg_trgm; once (available on Neon, Supabase, RDS).
Register sources in the project file src/genpm/search.ts, imported at startup: registerSearchSource(contentSearchSource('pages', { path: ({ slug }) => /${slug} })).
Build the index once and then daily: await reindexJob.enqueue({}) and schedule('search.reindex', '0 3 * * *') (@core/jobs).
Query: const { hits } = await search(q, { locale }), or mount searchRoutes() / searchRoute at /api/search.
Render snippets by mapping parts: hit.snippet.map(p => p.match ? <mark>{p.text}</mark> : p.text).
Verify: index a document and find it by the first letters of a word in its title.

Conventions

Sources yield plain text bodies (strip Markdown/HTML first, e.g. with toPlainText of @core/rich-text).
Pass locale when you know it: the query uses that language's stemmer and the GIN index.
Only index published, public content; private data never goes into search_documents.

Don't

Don't build SQL from the query string; search() already sanitizes it to words.
Don't render snippets with dangerouslySetInnerHTML.
Don't call reindex() inside a request: use the job.

# @core/search — rules for AI agents

## Purpose
Site search on Postgres full-text search: one `search_documents` table fed by any `SearchSource` (@core/contracts),
weighted title/body vectors with the stemmer of each document's language, prefix matching for search-as-you-type,
snippets returned as plain parts (never HTML) and, if the `pg_trgm` extension exists, a typo-tolerant fallback on
titles. No external engine, no semantic search.

## Map
- `index.ts` — public API: `search`, `registerSearchSource`, `reindex`, `indexDocument`, `removeDocument`, `reindexJob`.
- `search.ts` — indexing and querying. `schema.ts` — table and GIN index.
- `adapters/hono.ts` — `searchRoutes()`. `adapters/next.ts` — `searchRoute` (GET).

## Integration
1. Generate and apply migrations (see `src/lib/db/AGENTS.md`). Optional typo tolerance: run
   `create extension if not exists pg_trgm;` once (available on Neon, Supabase, RDS).
2. Register sources in the project file `src/genpm/search.ts`, imported at startup:
   `registerSearchSource(contentSearchSource('pages', { path: ({ slug }) => `/${slug}` }))`.
3. Build the index once and then daily: `await reindexJob.enqueue({})` and `schedule('search.reindex', '0 3 * * *')` (@core/jobs).
4. Query: `const { hits } = await search(q, { locale })`, or mount `searchRoutes()` / `searchRoute` at `/api/search`.
5. Render snippets by mapping parts: `hit.snippet.map(p => p.match ? <mark>{p.text}</mark> : p.text)`.
6. Verify: index a document and find it by the first letters of a word in its title.

## Conventions
- Sources yield plain text bodies (strip Markdown/HTML first, e.g. with `toPlainText` of @core/rich-text).
- Pass `locale` when you know it: the query uses that language's stemmer and the GIN index.
- Only index published, public content; private data never goes into `search_documents`.

## Don't
- Don't build SQL from the query string; `search()` already sanitizes it to words.
- Don't render snippets with `dangerouslySetInnerHTML`.
- Don't call `reindex()` inside a request: use the job.

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/search/adapters/hono.ts읽기 전용 · ae66128

// Adaptador Hono: `app.route('/api/search', searchRoutes())` → GET /api/search?q=taza&locale=es&type=product
import { Hono } from 'hono';
import { search } from '../index.ts';

export function searchRoutes() {
  return new Hono().get('/', async (c) => {
    const q = (c.req.query('q') ?? '').slice(0, 200);
    const types = c.req.queries('type');
    const res = await search(q, { locale: c.req.query('locale'), types, limit: Number(c.req.query('limit') ?? 10) || 10 });
    c.header('cache-control', 'public, max-age=60');
    return c.json(res);
  });
}