@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/schema.ts읽기 전용 · ae66128

// Tablas de @core/search. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { customType, index, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core';

const tsvector = customType<{ data: string }>({ dataType: () => 'tsvector' });

/** Índice de búsqueda: una fila por documento (`type` + `id`) con su vector ponderado (título A, cuerpo B). */
export const searchDocuments = pgTable(
  'search_documents',
  {
    type: text('type').notNull(),
    id: text('id').notNull(),
    locale: text('locale').notNull(),
    url: text('url').notNull(),
    title: text('title').notNull(),
    body: text('body').notNull(),
    /** Configuración de texto de Postgres usada (`spanish`, `english`, `simple`…). */
    config: text('config').notNull(),
    tsv: tsvector('tsv').notNull(),
    indexedAt: timestamp('indexed_at', { withTimezone: true, mode: 'date' }).notNull().defaultNow(),
  },
  (t) => [
    primaryKey({ columns: [t.type, t.id] }),
    index('search_documents_tsv_idx').using('gin', t.tsv),
    index('search_documents_locale_idx').on(t.locale, t.type),
  ],
);

export type SearchRow = typeof searchDocuments.$inferSelect;