docs(search): annotate search and parsing helpers

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: tae2089

internal/parse/treesitter/walker.go

@@ -232,6 +232,7 @@ func (w *Walker) executeQueries(root *sitter.Node, content []byte, filePath stri
 	var interfaces []interfaceInfo
 
 	// nodeKey → index in nodes slice for O(1) dedup lookup
+	// @intent key duplicate symbol matches by name and source span during one query execution.
 	type nodeKey struct {
 		name      string
 		startLine int
@@ -690,6 +691,8 @@ func (w *Walker) ExtractComments(ctx context.Context, filePath string, content [
 	return comments, nil
 }
 
+// parseSourceCtx parses one source buffer with cancellation support, returning the resulting tree.
+// @intent let long parses honor caller cancellation while reusing pooled parsers for throughput.
 func (w *Walker) parseSourceCtx(ctx context.Context, content []byte) (*sitter.Tree, error) {
 	if err := ctx.Err(); err != nil {
 		return nil, err
@@ -920,6 +923,7 @@ func (w *Walker) tryExtractDocstring(exprStmt *sitter.Node, content []byte) (Com
 	}
 }
 
+// @intent accept only Python string literal forms that can legally act as docstrings.
 func isSupportedPythonDocstringLiteral(text string) bool {
 	lower := strings.ToLower(text)
 	for _, quote := range []string{"\"\"\"", "'''"} {
@@ -985,6 +989,8 @@ func mergeCommentBlocks(comments, docstrings []CommentBlock) []CommentBlock {
 	return merged
 }
 
+// acquireParser borrows a Tree-sitter parser from the per-walker pool, creating one on first use.
+// @intent amortize parser construction cost across many parses on the same language.
 func (w *Walker) acquireParser() *sitter.Parser {
 	if w.lang == nil {
 		return nil
@@ -997,6 +1003,8 @@ func (w *Walker) acquireParser() *sitter.Parser {
 	return p
 }
 
+// releaseParser returns a parser instance to the pool for reuse.
+// @intent keep allocated parsers alive between parses instead of letting them be garbage collected.
 func (w *Walker) releaseParser(p *sitter.Parser) {
 	if p == nil || w.lang == nil {
 		return
@@ -1040,6 +1048,7 @@ func (w *Walker) getLanguage() (*sitter.Language, error) {
 
 // rangesOverlap reports whether two inclusive line ranges share at least one line.
 // @intent detect whether two symbol captures refer to overlapping source spans
+// @intent detect overlapping source spans when deduplicating competing Tree-sitter captures.
 func rangesOverlap(aStart, aEnd, bStart, bEnd int) bool {
 	return aStart <= bEnd && bStart <= aEnd
 }

internal/pathutil/exclude.go

@@ -116,6 +116,8 @@ func LoadIncludePathsFromConfig(dir string) ([]string, error) {
 	return cfg.IncludePaths, nil
 }
 
+// MatchIncludePaths reports whether relPath falls inside or is an ancestor of any configured include path.
+// @intent let walkers prune directories that lie outside user-selected include scopes while still descending into ancestors.
 func MatchIncludePaths(relPath string, includePaths []string) bool {
 	relPath = normalizeIncludePath(relPath)
 	for _, inc := range includePaths {
@@ -129,6 +131,7 @@ func MatchIncludePaths(relPath string, includePaths []string) bool {
 
 // HasPathPrefix reports whether path is the same as prefix or is nested under it.
 // Both inputs are normalized to slash-separated clean relative paths.
+// @intent compare include path scopes after normalization so callers can test path containment reliably.
 func HasPathPrefix(pathValue, prefix string) bool {
 	pathValue = normalizeIncludePath(pathValue)
 	prefix = normalizeIncludePath(prefix)
@@ -138,6 +141,8 @@ func HasPathPrefix(pathValue, prefix string) bool {
 	return pathValue == prefix || strings.HasPrefix(pathValue, prefix+"/")
 }
 
+// normalizeIncludePath converts user-supplied include paths to a comparable slash form.
+// @intent guarantee comparisons treat "./foo", "foo", and "foo/" as the same logical path.
 func normalizeIncludePath(p string) string {
 	clean := path.Clean(strings.ReplaceAll(filepath.ToSlash(strings.TrimSpace(p)), `\`, "/"))
 	if clean == "." {

internal/store/search/postgres.go

@@ -118,6 +118,12 @@ func (p *PostgresBackend) PurgeNamespace(ctx context.Context, db *gorm.DB) error
 	return nil
 }
 
+// resultRow scans node_id values from PostgreSQL tsquery matches.
+// @intent decode the single-column tsquery result before joining back to nodes.
+type resultRow struct {
+	NodeID uint
+}
+
 // Query는 PostgreSQL tsquery로 관련 노드를 검색한다.
 // @intent 사용자 검색어를 prefix tsquery로 변환해 관련 노드를 찾는다.
 // @requires limit는 0보다 커야 의미 있는 결과를 얻는다.
@@ -132,10 +138,6 @@ func (p *PostgresBackend) Query(ctx context.Context, db *gorm.DB, query string,
 	}
 	ns := ctxns.FromContext(ctx)
 
-	type resultRow struct {
-		NodeID uint
-	}
-
 	var rows []resultRow
 	querySQL := `
 		SELECT sd.node_id

internal/store/search/sanitize.go

@@ -1,10 +1,13 @@
+// @index Query sanitizers for backend-specific full-text search syntax.
 package search
 
 import (
 	"strings"
 	"unicode"
 )
 
+// sanitizeTokens extracts lowercase identifier-like terms from raw search input.
+// @intent normalize user queries into backend-safe tokens before they are embedded into FTS syntax.
 func sanitizeTokens(query string) []string {
 	fields := strings.FieldsFunc(query, func(r rune) bool {
 		return !(unicode.IsLetter(r) || unicode.IsDigit(r) || r == '_')
@@ -20,6 +23,7 @@ func sanitizeTokens(query string) []string {
 }
 
 // SanitizeFTS5 converts raw user input into a safe FTS5 prefix query.
+// @intent build SQLite FTS queries that preserve prefix matching without exposing parser-breaking characters.
 func SanitizeFTS5(query string) string {
 	tokens := sanitizeTokens(query)
 	if len(tokens) == 0 {
@@ -33,6 +37,7 @@ func SanitizeFTS5(query string) string {
 }
 
 // SanitizePostgresTSQuery converts raw user input into a safe prefix tsquery.
+// @intent translate free-form user input into a PostgreSQL tsquery that mirrors the SQLite prefix search behavior.
 func SanitizePostgresTSQuery(query string) string {
 	tokens := sanitizeTokens(query)
 	if len(tokens) == 0 {

internal/store/search/sqlite.go

@@ -97,6 +97,10 @@ func (s *SQLiteBackend) PurgeNamespace(ctx context.Context, db *gorm.DB) error {
 	return db.WithContext(ctx).Exec("DELETE FROM "+sqliteFTSTable+" WHERE namespace = ?", ctxns.FromContext(ctx)).Error
 }
 
+// rebuildTable clears all FTS rows for the current namespace in tableName and
+// repopulates them from search_documents in batches. Used by both full Rebuild
+// and the legacy-upgrade path.
+// @intent resynchronize one namespace-scoped SQLite FTS table from persisted search documents without disturbing other namespaces.
 func (s *SQLiteBackend) rebuildTable(ctx context.Context, db *gorm.DB, tableName string) error {
 	ns := ctxns.FromContext(ctx)
 	clearSQL := fmt.Sprintf("DELETE FROM %s WHERE namespace = ?", tableName)
@@ -125,6 +129,10 @@ func (s *SQLiteBackend) rebuildTable(ctx context.Context, db *gorm.DB, tableName
 	})
 }
 
+// rebuildTableNodes deletes and re-inserts FTS rows only for the given nodeIDs
+// within the current namespace, processing them in chunks of scopedRebuildChunkSize
+// to avoid oversized IN clauses.
+// @intent refresh only the requested node documents in SQLite FTS so incremental updates can avoid a full namespace rebuild.
 func (s *SQLiteBackend) rebuildTableNodes(ctx context.Context, db *gorm.DB, tableName string, nodeIDs []uint) error {
 	ns := ctxns.FromContext(ctx)
 	return db.WithContext(ctx).Transaction(func(outerTx *gorm.DB) error {
@@ -154,6 +162,10 @@ func (s *SQLiteBackend) rebuildTableNodes(ctx context.Context, db *gorm.DB, tabl
 	})
 }
 
+// insertSQLiteFTSBatch executes one bulk INSERT for a batch of search documents into an FTS table.
+// @intent push many rows in a single statement so rebuild paths avoid per-row round trips.
+// @sideEffect inserts rows into the supplied FTS virtual table.
+// @mutates search_fts virtual table contents
 func insertSQLiteFTSBatch(ctx context.Context, tx *gorm.DB, tableName string, docs []model.SearchDocument) error {
 	if len(docs) == 0 {
 		return nil
@@ -162,6 +174,10 @@ func insertSQLiteFTSBatch(ctx context.Context, tx *gorm.DB, tableName string, do
 	return tx.WithContext(ctx).Exec(insertSQL, args...).Error
 }
 
+// buildSQLiteFTSInsert constructs a bulk INSERT statement for the FTS virtual
+// table, returning the SQL string and its positional arguments. Each document
+// maps to a (node_id, content, language, namespace) value row.
+// @intent batch SQLite FTS inserts into one statement so rebuild paths can stream many documents with minimal per-row overhead.
 func buildSQLiteFTSInsert(tableName string, docs []model.SearchDocument) (string, []any) {
 	if len(docs) == 0 {
 		return "", nil
@@ -180,6 +196,12 @@ func buildSQLiteFTSInsert(tableName string, docs []model.SearchDocument) (string
 	return insertSQL, args
 }
 
+// ftsRow scans node_id values from search_fts MATCH queries.
+// @intent decode the single-column FTS result before joining back to nodes.
+type ftsRow struct {
+	NodeID uint
+}
+
 // Query는 FTS5 MATCH 질의로 관련 노드를 검색한다.
 // @intent 사용자 검색어를 SQLite FTS prefix 질의로 변환해 노드를 찾는다.
 // @requires limit는 0보다 커야 의미 있는 결과를 얻는다.
@@ -194,10 +216,6 @@ func (s *SQLiteBackend) Query(ctx context.Context, db *gorm.DB, query string, li
 	}
 	ns := ctxns.FromContext(ctx)
 
-	type ftsRow struct {
-		NodeID uint
-	}
-
 	var rows []ftsRow
 	querySQL := `SELECT CAST(node_id AS INTEGER) AS node_id
 		 FROM search_fts
@@ -245,6 +263,8 @@ func (s *SQLiteBackend) Query(ctx context.Context, db *gorm.DB, query string, li
 	return result, nil
 }
 
+// sqliteColumnExists reports whether a column is present on a given SQLite table via PRAGMA table_info.
+// @intent gate schema migrations on actual table layout instead of guessing from version markers.
 func sqliteColumnExists(db *gorm.DB, tableName, columnName string) (bool, error) {
 	rows, err := db.Raw("PRAGMA table_info(" + tableName + ")").Rows()
 	if err != nil {
@@ -266,6 +286,10 @@ func sqliteColumnExists(db *gorm.DB, tableName, columnName string) (bool, error)
 	return false, rows.Err()
 }
 
+// createSQLiteFTSTable issues a CREATE VIRTUAL TABLE … USING fts5 DDL for the
+// given tableName. When ifNotExists is true the statement is idempotent; when
+// false it is used for the upgrade shadow table where a fresh schema is required.
+// @intent create the namespace-aware SQLite FTS table shape used by both first-run migration and legacy upgrade flows.
 func createSQLiteFTSTable(db *gorm.DB, tableName string, ifNotExists bool) error {
 	clause := ""
 	if ifNotExists {
@@ -278,6 +302,11 @@ func createSQLiteFTSTable(db *gorm.DB, tableName string, ifNotExists bool) error
 	return db.Exec(stmt).Error
 }
 
+// upgradeLegacyFTSTable migrates a pre-namespace search_fts schema to the
+// current four-column layout (node_id, content, language, namespace). It builds
+// a shadow table, populates it via rebuildTable, then swaps it into place using
+// RENAME, keeping the old table as a backup until the swap succeeds.
+// @intent upgrade legacy SQLite FTS storage to the namespace-aware schema without losing the indexed search snapshot.
 func (s *SQLiteBackend) upgradeLegacyFTSTable(db *gorm.DB) error {
 	for _, tableName := range []string{sqliteFTSUpgradeTable, sqliteFTSLegacyBackup} {
 		if err := db.Exec(fmt.Sprintf("DROP TABLE IF EXISTS %s", tableName)).Error; err != nil {
@@ -306,6 +335,8 @@ func (s *SQLiteBackend) upgradeLegacyFTSTable(db *gorm.DB) error {
 	return nil
 }
 
+// sqliteTableExists reports whether a regular table with the given name exists in sqlite_master.
+// @intent let migration code branch on table presence without depending on GORM AutoMigrate side effects.
 func sqliteTableExists(db *gorm.DB, tableName string) (bool, error) {
 	var count int64
 	if err := db.Raw("SELECT count(*) FROM sqlite_master WHERE type = 'table' AND name = ?", tableName).Scan(&count).Error; err != nil {