Skip to content

CLAUDE.md

Latest commit

 

History

History
77 lines (57 loc) · 3.97 KB

CLAUDE.md

File metadata and controls

77 lines (57 loc) · 3.97 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

cs (codespelunker) is a command-line code search tool written in Go. It searches files recursively using boolean queries, regex, and fuzzy matching, with relevance ranking (BM25/TF-IDF). Four modes: console output, interactive TUI, HTTP server, and MCP server.

Build & Test Commands

go build -o cs                        # Build binary
go test ./...                         # Run all tests
go test -v ./...                      # Verbose tests
go test -run TestPreParseQuery ./...  # Run a single test

Linting:

golangci-lint run --enable=gofmt ./...
gofmt -s -w -l .

Architecture

Root package main plus subpackages under pkg/. The search pipeline is orchestrated by DoSearch() in search.go:

FileWalker → [read + filter files] → AST query evaluation → matched FileJobs channel

Query Pipeline (pkg/search/)

Queries are parsed into an AST and evaluated against each file:

Lexer → Parser → Transformer → Planner → Executor
  • Lexer (lexer.go): tokenizes query string (terms, quotes, regex, operators, fuzzy markers)
  • Parser (parser.go): builds AST with boolean logic (AND/OR/NOT), quoted phrases, regex /pattern/, fuzzy ~1/~2
  • Transformer (transformer.go): semantic rewrites (e.g. complexity=high)
  • Planner (planner.go): query optimization
  • Executor (executor.go): evaluates AST against file content, returns match locations
  • Extractor (extractor.go): extracts matched terms for highlighting
  • AST (ast.go): AST node type definitions (AndNode, OrNode, NotNode, KeywordNode, PhraseNode, RegexNode, FuzzyNode, FilterNode)
  • Document (document.go): Document and SearchResult structs

See pkg/search/README.md for detailed query syntax documentation.

Core Root Files

  • main.go: Cobra CLI entry point. Routes to ConsoleSearch(), TUI (initialModel()), StartHttpServer(), or StartMcpServer() based on flags/args
  • config.go: Config struct with all CLI-configurable fields. DefaultConfig() provides sensible defaults
  • search.go: DoSearch() — orchestrates the full search pipeline: file walking, reading, binary/minified filtering, AST evaluation, and result streaming via channels. Uses SearchCache for prefix-based caching
  • console.go: ConsoleSearch() — collects results, ranks, and outputs in text/JSON/vimgrep format
  • tui.go: bubbletea TUI with lipgloss styling. Debounced search input, incremental result streaming, syntax-highlighted preview
  • http.go: HTTP server with embedded templates, search/display endpoints, theme support (dark/light/bare), custom template overrides
  • cache.go: SearchCache — LRU cache with TTL for query results; supports prefix matching for progressive refinement in TUI
  • syntax.go: Syntax highlighting with keyword tables for 80+ languages
  • language.go: Language detection via scc processor's language database
  • mcp.go: MCP (Model Context Protocol) server over stdio; exposes search as a tool for AI agents
  • templates.go: Template loading with //go:embed for built-in HTML templates; supports custom template paths

Subpackages

  • pkg/common/: FileJob struct — the core data type passed through the pipeline
  • pkg/ranker/: RankResults() — BM25 (default), TF-IDF, or simple ranking with location-based boosting. Includes declaration detection (declarations.go), deduplication (dedup.go), and stopword filtering (stopwords.go)
  • pkg/snippet/: Snippet extraction (sliding window) and line-based extraction; auto-selects mode by file type

Key Conventions

  • Dependencies are vendored (vendor/ directory)
  • SPDX license headers on all source files (MIT)
  • TUI uses bubbletea + bubbles (text input) + lipgloss (styling)
  • Releases via GoReleaser (.goreleaser.yaml)
  • Go 1.25.2, module: github.com/boyter/cs