sweet-search 0.0.1 → 2.3.0

package/core/infrastructure/config/search.js

@@ -0,0 +1,396 @@
+/**
+ * Search Configuration — file patterns, routing, performance targets.
+ * Split from core/config.js during DDD migration.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+
+// =============================================================================
+// QUERY ROUTING CONFIGURATION
+// =============================================================================
+
+export const ROUTING_CONFIG = {
+  lexicalPatterns: [
+    /^[A-Z][a-zA-Z0-9]*$/,           // CamelCase (starts with capital)
+    /^[a-z]+[A-Z][a-zA-Z0-9]*$/,     // camelCase (has capital in middle) - Fix #3
+    /^[a-z][a-z0-9_]*_[a-z0-9_]+$/,  // snake_case (must have underscore) - Fix #3
+    /^[A-Z_][A-Z0-9_]*$/,            // SCREAMING_SNAKE
+    /\.(java|js|jsx|ts|tsx|proto)$/, // File extensions
+    /\/|\\/,                          // Paths
+    /"[^"]*"/,                        // Quoted strings
+    /\bclass\s+\w+/,
+    /\bfunction\s+\w+/,
+    /\binterface\s+\w+/,
+    // Fix #5: Code Structural Keywords
+    /\b(method|constructor|field|property|annotation|decorator|enum|abstract|static|final|private|public|protected)\b/i,
+    /^@\w+/,  // Annotations: @Override, @Test
+    /\b(extends|implements)\s+\w+/i,
+  ],
+  semanticPatterns: [
+    /how\s+(does|do|to|can)/i,
+    /what\s+(is|are|does)/i,
+    /why\s+(does|is|are)/i,
+    /where\s+(is|are|does)/i,
+    /find\s+.*\s+(that|which)/i,
+    /\s+(related|similar)\s+to/i,
+    /implement/i,
+    /handle|handling/i,
+    /work(s|ing)?/i,
+    // Fix #4: Imperative Command Detection
+    /^(list|show|find|get|fetch|retrieve|search|locate)\s+(all|any)/i,
+    /^(list|show|display)\s+/i,
+  ],
+  defaultMode: 'hybrid',
+};
+
+// =============================================================================
+// FILE PATTERNS
+// =============================================================================
+
+export const FILE_PATTERNS = {
+  include: [
+    // Source code (all major languages)
+    '**/*.{js,jsx,ts,tsx,mjs,cjs}',      // JavaScript/TypeScript
+    '**/*.{java,kt,kts,scala,groovy}',    // JVM
+    '**/*.{py,pyi}',                       // Python
+    '**/*.go',                              // Go
+    '**/*.rs',                              // Rust
+    '**/*.{c,cpp,cc,cxx,h,hpp,hxx}',      // C/C++
+    '**/*.{cs,fs,vb}',                     // .NET
+    '**/*.{rb,erb}',                       // Ruby
+    '**/*.php',                             // PHP
+    '**/*.{swift,m,mm}',                   // Apple
+    '**/*.{lua,zig,nim,ex,exs}',           // Other
+    '**/*.{sh,bash,zsh,fish,ps1}',         // Shell
+    '**/*.sql',                             // SQL
+    '**/*.proto',                           // Protobuf
+    '**/*.{graphql,gql}',                  // GraphQL
+    // Config & docs
+    '**/*.{json,jsonc,json5}',              // JSON
+    '**/*.{yaml,yml}',                      // YAML
+    '**/*.toml',                             // TOML
+    '**/*.{xml,xsl,xsd,wsdl,pom,csproj}',  // XML
+    '**/*.{md,mdx,mdc,rst,txt}',           // Documentation + Cursor rules
+    '**/*.{html,htm,xhtml,vue,svelte}',    // Web markup/SFC
+    '**/*.{css,scss,sass,less}',           // Stylesheets
+    '**/*.svg',                             // SVG
+    // Build & deploy
+    '**/Dockerfile',                       // Dockerfile
+    '**/Dockerfile.*',                     // Dockerfile variants
+    '**/*.dockerfile',                     // Dockerfile alt extension
+    '**/Makefile',                         // Makefile
+    '**/*.mk',                            // Makefile includes
+    // Project markers
+    '**/CLAUDE.md',
+    '**/AGENTS.md',
+    '**/README.md',
+    '**/.cursorrules',
+    '**/.clinerules',
+    '**/.roorules',
+    '**/.roorules-*',
+    '**/.windsurfrules',
+    '**/.aider.conf.yml',
+  ],
+  exclude: [
+    // ── Package manager dependencies ──────────────────────────────────────
+    '**/node_modules/**',
+    '**/bower_components/**',
+    '**/jspm_packages/**',
+    '**/.yarn/**',
+    '**/.pnp.*',
+    '**/vendor/**',
+    '**/vendors/**',
+    '**/third_party/**',
+    '**/thirdparty/**',
+    '**/.cargo/**',
+    '**/Godeps/**',
+    '**/Pods/**',
+    '**/Carthage/**',
+    '**/.gradle/**',
+    '**/.mvn/**',
+    '**/venv/**',
+    '**/.venv/**',
+    '**/site-packages/**',
+    '**/_esy/**',
+
+    // ── Build outputs & generated code ────────────────────────────────────
+    '**/target/**',
+    '**/build/**',
+    '**/dist/**',
+    '**/out/**',
+    '**/.next/**',
+    '**/.nuxt/**',
+    '**/.output/**',
+    '**/.svelte-kit/**',
+    '**/.turbo/**',
+    '**/.angular/**',
+    '**/.parcel-cache/**',
+    '**/storybook-static/**',
+    '**/__generated__/**',
+    '**/generated/**',
+    '**/.vercel/**',
+    '**/.netlify/**',
+    '**/.serverless/**',
+    '**/.aws-sam/**',
+    '**/.terraform/**',
+
+    // ── VCS & IDE ─────────────────────────────────────────────────────────
+    '**/.git/**',
+    '**/.idea/**',
+    '**/.vscode/**',
+    '**/.vs/**',
+    '**/.eclipse/**',
+    '**/.settings/**',
+
+    // ── Caches & temp ─────────────────────────────────────────────────────
+    '**/.vite/**',
+    '**/coverage/**',
+    '**/.coverage/**',
+    '**/__pycache__/**',
+    '**/.mypy_cache/**',
+    '**/.pytest_cache/**',
+    '**/.ruff_cache/**',
+    '**/.tox/**',
+    '**/.eggs/**',
+    '**/*.egg-info/**',
+    '**/.pytype/**',
+    '**/htmlcov/**',
+    '**/.cache/**',
+    '**/.nx/**',
+    '**/.eslintcache',
+    '**/.stylelintcache',
+    '**/tmp/**',
+    '**/.tmp/**',
+    '**/.temp/**',
+
+    // ── Lock files (all ecosystems) ───────────────────────────────────────
+    '**/package-lock.json',
+    '**/bun.lock',
+    '**/bun.lockb',
+    '**/yarn.lock',
+    '**/pnpm-lock.yaml',
+    '**/composer.lock',
+    '**/Cargo.lock',
+    '**/Gemfile.lock',
+    '**/poetry.lock',
+    '**/pdm.lock',
+    '**/uv.lock',
+    '**/Pipfile.lock',
+    '**/npm-shrinkwrap.json',
+    '**/deno.lock',
+    '**/pixi.lock',
+    '**/flake.lock',
+    '**/gradle.lockfile',
+    '**/.terraform.lock.hcl',
+    '**/go.sum',
+    '**/Package.resolved',
+
+    // ── Minified / bundled / sourcemaps ───────────────────────────────────
+    '**/*.min.js',
+    '**/*.min.mjs',
+    '**/*.min.cjs',
+    '**/*.min.css',
+    '**/*.bundle.js',
+    '**/*.bundle.css',
+    '**/*.umd.js',
+    '**/*.iife.js',
+    '**/*.chunk.js',
+    '**/*.map',
+
+    // ── Test snapshots ────────────────────────────────────────────────────
+    '**/*.snap',
+
+    // ── Binary & compiled artifacts ───────────────────────────────────────
+    '**/*.class',
+    '**/*.pyc',
+    '**/*.pyo',
+    '**/*.o',
+    '**/*.so',
+    '**/*.dylib',
+    '**/*.dll',
+    '**/*.exe',
+    '**/*.wasm',
+
+    // ── OS metadata & misc ────────────────────────────────────────────────
+    '**/*.log',
+    '**/.DS_Store',
+    '**/Thumbs.db',
+    '**/*.swp',
+    '**/*.swo',
+
+    // ── Secrets & environment files (all stacks) ────────────────────────
+    '**/.env',
+    '**/.env.*',
+
+    // ── .NET secrets & env-specific config ────────────────────────────────
+    '**/appsettings.Development.json',
+    '**/appsettings.Local.json',
+    '**/appsettings.Staging.json',
+    '**/appsettings.Production.json',
+    '**/secrets.json',
+    '**/*.user',
+
+    // ── Python (Django, FastAPI, Flask) secrets ───────────────────────────
+    '**/local_settings.py',
+    '**/settings/local.py',
+    '**/settings/dev.py',
+    '**/secrets.py',
+    '**/config/local.py',
+
+    // ── Java/Kotlin (Spring) env-specific config ─────────────────────────
+    '**/application-dev.properties',
+    '**/application-local.properties',
+    '**/application-test.properties',
+    '**/application-*-local.yml',
+    '**/application-*-local.yaml',
+
+    // ── Node/JS/TS secrets ────────────────────────────────────────────────
+    '**/config/secrets.js',
+    '**/config/secrets.ts',
+    '**/config/local.js',
+    '**/config/local.ts',
+    '**/config.local.js',
+    '**/config.local.ts',
+    '**/.firebaserc',
+
+    // ── Ruby (Rails) ──────────────────────────────────────────────────────
+    '**/config/credentials.yml.enc',
+
+    // ── PHP (Laravel) ─────────────────────────────────────────────────────
+    '**/config/local.php',
+
+    // ── Go / Rust / generic local config ──────────────────────────────────
+    '**/config.local.*',
+    '**/config/local.*',
+
+    // ── Mobile: iOS ───────────────────────────────────────────────────────
+    '**/Secrets.plist',
+    '**/GoogleService-Info.plist',
+    '**/*-Credentials.plist',
+    '**/Config/Secrets.swift',
+
+    // ── Mobile: Android ───────────────────────────────────────────────────
+    '**/local.properties',
+    '**/google-services.json',
+    '**/keystore.properties',
+    '**/secrets.properties',
+
+    // ── Embedded (Arduino, ESP-IDF, PlatformIO) ──────────────────────────
+    '**/credentials.h',
+    '**/secrets.h',
+    '**/config_private.h',
+    '**/sdkconfig.local',
+    '**/platformio.ini.local',
+    '**/*_credentials.*',
+
+    // ── Sweet Search data ─────────────────────────────────────────────────
+    '**/.sweet-search/**',
+  ],
+
+  // Default max file size for indexing (1 MB). Files larger than this are
+  // almost always generated data, minified bundles, or binary blobs that
+  // add noise without meaningful search value.  Override per-project via
+  // "maxFileSize" in .sweet-search.config.json (value in bytes).
+  maxFileSize: 1 * 1024 * 1024,
+
+  // Align indexing with .gitignore by default. Agentic paths are allowlisted
+  // in AGENTIC_GITIGNORE_ALLOWLIST so local AI setup remains searchable.
+  respectGitignore: true,
+};
+
+// Agentic tooling paths that should stay indexable even when listed in
+// .gitignore. This supports local AI workflow files without requiring users
+// to maintain extra include rules.
+export const AGENTIC_GITIGNORE_ALLOWLIST = {
+  directories: [
+    '.claude/',
+    '.agents/',
+    '.cursor/',
+    '.codex/',
+    '.cline/',
+    '.clinerules/',
+    '.roo/',
+    '.continue/',
+    '.windsurf/',
+  ],
+  files: [
+    '.cursorrules',
+    '.clinerules',
+    '.roorules',
+    '.windsurfrules',
+    '.aider.conf.yml',
+    '.aider.conf.yaml',
+  ],
+  filePrefixes: [
+    '.roorules-',
+    '.aider.',
+  ],
+};
+
+/**
+ * Load per-project configuration from .sweet-search.config.json
+ * Precedence: config file > defaults. Environment variables > config file.
+ *
+ * @param {string} [projectRoot] - Project root to search for config file
+ * @returns {{ include: string[], exclude: string[], maxFileSize: number, respectGitignore: boolean, projectRoot?: string }}
+ */
+export function loadProjectConfig(projectRoot = process.cwd()) {
+  const configPath = path.join(projectRoot, '.sweet-search.config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      include: FILE_PATTERNS.include,
+      exclude: FILE_PATTERNS.exclude,
+      maxFileSize: FILE_PATTERNS.maxFileSize,
+      respectGitignore: FILE_PATTERNS.respectGitignore,
+    };
+  }
+
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+
+    // Validate known keys, warn on unknown
+    const knownKeys = new Set(['include', 'exclude', 'projectRoot', 'indexDocs', 'maxFileSize', 'respectGitignore', 'lateInteractionModel', 'cascade']);
+    for (const key of Object.keys(config)) {
+      if (!knownKeys.has(key)) {
+        console.error(`[sweet-search] Warning: unknown key "${key}" in .sweet-search.config.json`);
+      }
+    }
+
+    return {
+      include: Array.isArray(config.include) ? config.include : FILE_PATTERNS.include,
+      exclude: Array.isArray(config.exclude) ? [...FILE_PATTERNS.exclude, ...config.exclude] : FILE_PATTERNS.exclude,
+      maxFileSize: typeof config.maxFileSize === 'number' ? config.maxFileSize : FILE_PATTERNS.maxFileSize,
+      respectGitignore: typeof config.respectGitignore === 'boolean' ? config.respectGitignore : FILE_PATTERNS.respectGitignore,
+      ...(config.projectRoot ? { projectRoot: config.projectRoot } : {}),
+      ...(config.lateInteractionModel !== undefined ? { lateInteractionModel: config.lateInteractionModel } : {}),
+      ...(config.cascade ? { cascade: config.cascade } : {}),
+    };
+  } catch (err) {
+    console.error(`[sweet-search] Error loading .sweet-search.config.json: ${err.message}`);
+    return {
+      include: FILE_PATTERNS.include,
+      exclude: FILE_PATTERNS.exclude,
+      maxFileSize: FILE_PATTERNS.maxFileSize,
+      respectGitignore: FILE_PATTERNS.respectGitignore,
+    };
+  }
+}
+
+// =============================================================================
+// PERFORMANCE TARGETS
+// =============================================================================
+
+export const PERFORMANCE_TARGETS = {
+  latency: {
+    lexicalP50: 10,
+    hnswLookupP50: 1,
+    semanticP50: 150,
+    rerankP50: 100,
+  },
+  accuracy: {
+    topKRecall: 0.85,
+  },
+};

package/core/infrastructure/config/translation.js

@@ -0,0 +1,89 @@
+/**
+ * Cerebras LLM Configuration — fast inference for HCGS and graph summary generation.
+ * Split from core/config.js during DDD migration.
+ */
+
+const CEREBRAS_API_KEY = process.env.CEREBRAS_API_KEY || '';
+const GROQ_API_KEY = process.env.GROQ_API_KEY || '';
+const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY || '';
+
+// =============================================================================
+// CEREBRAS GLM CONFIGURATION (Fast Standalone LLM)
+// Reference: https://inference-docs.cerebras.ai/models/zai-glm-46
+// =============================================================================
+
+export const CEREBRAS_CONFIG = {
+  enabled: CEREBRAS_API_KEY.length > 0,
+  apiKey: CEREBRAS_API_KEY,
+  baseUrl: 'https://api.cerebras.ai/v1',
+
+  // Available models (December 2025)
+  // Run: node -e "fetch('https://api.cerebras.ai/v1/models', {headers:{'Authorization':'Bearer '+process.env.CEREBRAS_API_KEY}}).then(r=>r.json()).then(d=>d.data.forEach(m=>console.log(m.id)))"
+  models: {
+    // GLM-4.6: Best general purpose reasoning (~1000 tok/s)
+    'glm-4.6': {
+      id: 'zai-glm-4.6',
+      contextLength: 131072,  // 131K
+      features: ['reasoning', 'tool_use', 'json_mode'],
+      speed: '1000+ tok/s',
+      strengths: ['general', 'fast', 'reasoning'],
+    },
+    // Qwen 3 235B: Large MoE model for complex tasks
+    'qwen3-235b': {
+      id: 'qwen-3-235b-a22b-instruct-2507',
+      contextLength: 32768,
+      features: ['instruct'],
+      speed: '500+ tok/s',
+      strengths: ['complex', 'multilingual'],
+    },
+    // Llama 3.3 70B: Strong all-rounder
+    'llama-70b': {
+      id: 'llama-3.3-70b',
+      contextLength: 128000,
+      features: ['instruct', 'tool_use'],
+      speed: '800+ tok/s',
+      strengths: ['coding', 'general'],
+    },
+    // Llama 3.1 8B: Fast small model
+    'llama-8b': {
+      id: 'llama3.1-8b',
+      contextLength: 128000,
+      features: ['instruct'],
+      speed: '2000+ tok/s',
+      strengths: ['fast', 'simple'],
+    },
+    // Qwen 3 32B: Good balance of speed and quality
+    'qwen3-32b': {
+      id: 'qwen-3-32b',
+      contextLength: 32768,
+      features: ['instruct'],
+      speed: '1000+ tok/s',
+      strengths: ['balanced', 'multilingual'],
+    },
+  },
+
+  // Default model for different use cases
+  defaults: {
+    fast: 'zai-glm-4.6',           // Speed + quality balance
+    coding: 'llama-3.3-70b',       // Best for code
+    simple: 'llama3.1-8b',         // Quick simple tasks
+    hcgs: 'llama3.1-8b',           // Summary generation (fast, cheap — GLM-4.6 is overkill)
+    complex: 'qwen-3-235b-a22b-instruct-2507',  // Complex reasoning
+  },
+
+  // Reasoning mode (disable for faster direct responses)
+  reasoning: {
+    // disable_reasoning: true skips chain-of-thought
+    fastMode: true,  // Default: no CoT for speed
+  },
+};
+
+export function isCerebrasAvailable() {
+  return CEREBRAS_CONFIG.enabled;
+}
+
+export function getCerebrasModel(useCase = 'fast') {
+  return CEREBRAS_CONFIG.defaults[useCase] || CEREBRAS_CONFIG.defaults.fast;
+}
+
+// HCGS_CONFIG lives in ./graph.js (graph-related, not Cerebras)

package/core/infrastructure/config/vector-store.js

@@ -0,0 +1,114 @@
+/**
+ * Vector Store Configuration — HNSW, Binary HNSW, SEISMIC indices.
+ * Split from core/config.js during DDD migration.
+ */
+
+import { EMBEDDING_CONFIG } from './embedding.js';
+
+// =============================================================================
+// HNSW INDEX CONFIGURATION
+// =============================================================================
+
+export const HNSW_CONFIG = {
+  // Dimension matches active provider's HNSW dimension
+  get dimension() {
+    return EMBEDDING_CONFIG.hnswDimension;
+  },
+
+  // Index construction
+  M: 16,                     // Bi-directional links
+  efConstruction: 200,       // Construction-time candidate list
+
+  // Search parameters
+  efSearch: 100,             // Query-time candidate list
+
+  // Distance metric
+  metric: 'cosine',
+
+  // Memory settings
+  maxElements: 100000,
+};
+
+// =============================================================================
+// BINARY HNSW INDEX CONFIGURATION (32x memory reduction, 10x faster search)
+// Reference: https://huggingface.co/blog/embedding-quantization
+// =============================================================================
+
+export const BINARY_HNSW_CONFIG = {
+  // Binary dimension = float dimension / 8 (bits to bytes)
+  // 512d float → 64 bytes binary
+  get dimension() {
+    return Math.ceil(EMBEDDING_CONFIG.hnswDimension / 8);
+  },
+
+  // Float dimension for rescore stage
+  get floatDimension() {
+    return EMBEDDING_CONFIG.hnswDimension;
+  },
+
+  // Index construction (can be more aggressive since search is cheap)
+  M: 64,                     // Dense graph for fast convergence + recall
+  efConstruction: 800,       // High ef for quality graph construction
+
+  // Search parameters
+  efSearch: 400,             // Higher budget — adaptive ef reduces for easy queries
+
+  // Distance metric
+  metric: 'hamming',
+
+  // Memory settings (can hold more since binary is 32x smaller)
+  maxElements: 500000,
+
+  // 3-stage retrieval configuration
+  retrieval: {
+    stage1Candidates: 1000,  // Binary HNSW retrieves top 1000
+    stage2Candidates: 200,   // Int8 rescores top 200 (legacy fixed, used as maxStage2 fallback)
+    stage2_5Candidates: 200, // Float rescore pool size (legacy fixed, used as maxStage2_5 fallback)
+    stage3Candidates: 20,    // Reranker sees top 20
+
+    // Phase 1 flag: batched normalized-dot Stage 2 scoring.
+    // When false, falls back to per-candidate int8CosineSimilarity.
+    useBatchedDot: true,
+
+    // Phase 3: Adaptive oversampling (replaces fixed 200/200 pools)
+    // Pool sizes derived from k × oversample, adjusted by score spread.
+    adaptive: {
+      minStage2: 40,         // Hard minimum for Stage 2 pool
+      maxStage2: 400,        // Hard maximum for Stage 2 pool
+      oversample1: 10,       // Stage 2 base = k × oversample1
+      minStage2_5: 20,       // Hard minimum for Stage 2.5 pool
+      maxStage2_5: 200,      // Hard maximum for Stage 2.5 pool
+      oversample2: 5,        // Stage 2.5 base = k × oversample2
+    },
+  },
+
+  // Insertion order for graph quality ('sequential' | 'shuffle' | 'diversity')
+  insertionOrder: 'shuffle',
+
+  // Adaptive early termination thresholds (Fix 4).
+  // Tune via parameter sweep; values below are starting heuristics.
+  earlyTermination: {
+    windowSize: 16,             // Sliding window for discovery rate
+    // [progressThreshold, discoveryRateThreshold]
+    // "If progress > X and discoveryRate < Y, stop."
+    thresholds: [
+      [0.3, 0.05],  // Mature search with near-zero discovery
+      [0.6, 0.10],  // Well-explored with diminishing returns
+    ],
+  },
+};
+
+// =============================================================================
+// SEISMIC SPARSE VECTOR INDEX CONFIGURATION
+// =============================================================================
+// SEISMIC: block-based inverted index with summary pruning for learned sparse
+// embeddings (SPLADE, etc.). Third retrieval pathway alongside FTS5 + HNSW.
+// Currently DISABLED: requires a code-specific sparse encoder (SPLADE or similar)
+// that is not yet available. See docs/AST_OPTIMIZATIONS.md #12 for full plan.
+
+export const SEISMIC_CONFIG = {
+  enabled: false,  // Disabled by default until sparse encoder is available
+  blockSize: 64,   // Postings per block in inverted lists
+  alpha: 0.8,      // Importance fraction (reserved for future scoring tuning)
+  weight: 0.2,     // Weight in reciprocal rank fusion (when enabled)
+};

package/core/infrastructure/constants.js

@@ -0,0 +1,86 @@
+/**
+ * Shared constants for sweet-search
+ * Extracted to prevent drift between graph-search.js and sweet-search.js
+ */
+
+export const SYMBOL_KIND_WEIGHTS = {
+  class: 1.0,
+  interface: 0.95,
+  struct: 0.95,
+  enum: 0.9,
+  function: 0.85,
+  method: 0.80,
+  constructor: 0.75,
+  constant: 0.7,
+  property: 0.65,
+  field: 0.6,
+  variable: 0.4,
+  parameter: 0.3,
+  reference: 0.2,
+  call: 0.15,
+  import: 0.1,
+};
+
+export const DEFINITION_TYPES = new Set([
+  'class', 'interface', 'struct', 'enum', 'function', 'method', 'constructor'
+]);
+
+/**
+ * Canonical set of code file extensions recognized by sweet-search.
+ * Used by both the indexer (sparse gram builder) and the search pipeline
+ * (ripgrep type filter + code file detection). Single source of truth.
+ */
+export const CODE_FILE_EXTENSIONS = new Set([
+  'js', 'ts', 'jsx', 'tsx', 'py', 'rs', 'go', 'java', 'c', 'cpp', 'h', 'hpp',
+  'cs', 'rb', 'php', 'swift', 'kt', 'scala', 'lua', 'sh', 'zig', 'hs', 'ml',
+  'ex', 'exs', 'clj', 'erl', 'r', 'jl', 'dart', 'v', 'nim', 'cr', 'd', 'f90',
+  'ada', 'pas', 'cob', 'pl', 'pm', 'sql', 'graphql', 'proto', 'yaml', 'yml',
+  'json', 'toml', 'xml', 'html', 'css', 'scss', 'sass', 'less', 'svelte',
+  'vue', 'astro', 'mdx',
+]);
+
+/**
+ * Ripgrep type definition glob matching CODE_FILE_EXTENSIONS.
+ * Used with --type-add to define a custom 'code' type for ripgrep.
+ */
+export const RIPGREP_CODE_TYPE_GLOB =
+  'code:*.{js,ts,jsx,tsx,py,rs,go,java,c,cpp,h,hpp,cs,rb,php,swift,kt,scala,lua,sh,zig,hs,ml,ex,exs,clj,erl,r,jl,dart,v,nim,cr,d,f90,ada,pas,cob,pl,pm,sql,graphql,proto,yaml,yml,json,toml,xml,html,css,scss,sass,less,svelte,vue,astro,mdx}';
+
+/**
+ * Sparse gram symbol type bitmasks.
+ * These bit positions must match the Rust native addon's expectations.
+ * Used by both the indexer (to tag files) and the search pipeline (to filter).
+ */
+export const SPARSE_SYMBOL_MASKS = {
+  function: 1 << 0,
+  class: 1 << 1,
+  method: 1 << 2,
+  import: 1 << 3,
+  type: 1 << 4,
+  other: 1 << 5,
+};
+
+/**
+ * Resolve a symbol type string to its sparse gram bitmask value.
+ * @param {string} symbolType
+ * @returns {number} bitmask (0 if unrecognized)
+ */
+export function resolveSparseSymbolMask(symbolType) {
+  if (typeof symbolType !== 'string') return 0;
+
+  const normalized = symbolType.trim().toLowerCase();
+  if (!normalized) return 0;
+  if (normalized.includes('function')) return SPARSE_SYMBOL_MASKS.function;
+  if (normalized.includes('method')) return SPARSE_SYMBOL_MASKS.method;
+  if (normalized.includes('class')) return SPARSE_SYMBOL_MASKS.class;
+  if (normalized.includes('import')) return SPARSE_SYMBOL_MASKS.import;
+  if (
+    normalized.includes('type') ||
+    normalized.includes('interface') ||
+    normalized.includes('enum') ||
+    normalized.includes('typedef')
+  ) {
+    return SPARSE_SYMBOL_MASKS.type;
+  }
+  return SPARSE_SYMBOL_MASKS.other;
+}