reflex-search 1.0.2

# Semantic Query Building - LLM Prompt

## Task

Translate natural language questions about code into precise query commands for Reflex (a local code search engine).

**IMPORTANT:** Generate commands WITHOUT the 'rfx' prefix. Commands should start with 'query', not 'rfx query'.

## Syntax Reference

| Flag | Purpose | Example |
|------|---------|---------|
| `<pattern>` | Search text (required) | `query "extract_symbols"` |
| `--symbols` or `-s` | **Symbol-only mode**: Find where code is DEFINED (functions, classes, methods declared) | `--symbols` |
| `--kind <type>` or `-k` | Filter to specific symbol type - **automatically enables symbol-only mode** | `--kind function` |
| `--lang <lang>` or `-l` | Filter by language | `--lang rust` |
| `--regex` or `-r` | Regex pattern matching | `-r "fn.*test"` |
| `--exact` | Exact symbol name match | `--exact` |
| `--contains` | Use substring matching (expansive) | `--contains` |
| `--file <path>` or `-f` | Filter by file path substring | `--file src/parser` |
| `--glob <pattern>` or `-g` | Include files matching glob (can repeat) | `--glob "src/**/*.rs"` |
| `--exclude <pattern>` or `-x` | Exclude files matching glob (can repeat) | `--exclude "target/**"` |
| `--limit <n>` or `-n` | Maximum number of results | `--limit 10` |
| `--offset <n>` or `-o` | Skip first N results (pagination) | `--offset 20` |
| `--paths` or `-p` | Return only file paths (no content) | `--paths` |
| `--expand` | Show full symbol body | `--expand` |
| `--count` or `-c` | Count matches only | `--count` |
| `--dependencies` | Include dependency information | `--dependencies` |

**Symbol kinds:** `function`, `class`, `struct`, `enum`, `interface`, `method`, `constant`, `variable`, `trait`, `module`

**Possible `--lang` values:** `rust`, `python`, `typescript`, `javascript`, `go`, `java`, `c`, `cpp`, `csharp`, `php`, `ruby`, `kotlin`, `zig`, `vue`, `svelte`

**CRITICAL: `--lang` accepts ONLY ONE language per query. DO NOT use comma-separated languages:**

❌ **WRONG** - Comma-separated languages (will fail):
```
query "keycloak" --lang typescript,vue
```

✓ **CORRECT** - Separate queries for each language:
```
# Query 1: Search TypeScript files
query "keycloak" --lang typescript

# Query 2: Search Vue files
query "keycloak" --lang vue
```

## Regex Pattern Syntax

When using `--regex` flag, use standard regex syntax. **IMPORTANT: Special characters do NOT need backslash escaping in patterns.**

**Common regex operators (NO backslash needed):**

| Operator | Meaning | Example | Matches |
|----------|---------|---------|---------|
| `|` | Alternation (OR) | `belongsTo|hasMany` | "belongsTo" OR "hasMany" |
| `.` | Any character | `get.value` | "getValue", "get_value", etc. |
| `.*` | Zero or more chars | `import.*from` | "import foo from", "import { x } from", etc. |
| `^` | Start of line | `^fn ` | Lines starting with "fn " |
| `$` | End of line | `;$` | Lines ending with ";" |
| `\w` | Word character | `test_\w+` | "test_foo", "test_bar", etc. |
| `\d` | Digit | `version_\d` | "version_1", "version_2", etc. |

**Examples:**

✓ **CORRECT** - Alternation (OR):
```
query "belongsTo|hasMany|hasOne" --regex
```

❌ **WRONG** - Escaped pipes (matches literal backslash):
```
query "belongsTo\\|hasMany\\|hasOne" --regex
```

✓ **CORRECT** - Match function calls:
```
query "^import.*from" --regex
```

✓ **CORRECT** - Match test functions:
```
query "fn.*test|test.*fn" --regex --lang rust
```

## Understanding --symbols: Definitions vs Usages

**CRITICAL DISTINCTION:**

**Symbol mode (`--symbols` or `--kind`)**: Finds where code is **DEFINED/DECLARED**
- Function definitions: `function myFunc() { ... }`
- Class definitions: `class MyClass { ... }`
- Method definitions: `public function myMethod() { ... }`

**Full-text mode (default - no `--symbols`)**: Finds **ALL occurrences** (definitions + calls/usages)
- Function calls: `myFunc(param)`
- Class instantiations: `new MyClass()`
- Method calls: `$obj->myMethod()`

**Common mistake - DO NOT use `--symbols` or `--kind` for calls/usages:**

❌ **WRONG**: `query "belongsTo" --kind method --file User.php`
   - This finds where `belongsTo` **method is defined** (in Laravel framework code, not your file)
   - Result: Empty or wrong file

✓ **CORRECT**: `query "belongsTo" --file User.php`
   - This finds where `belongsTo` **is called** (in your User model)
   - Result: Shows relationship definitions in your code

❌ **WRONG**: `query "fetchData" --symbols --kind method --file api.js`
   - Looks for `fetchData` **method definition** (probably doesn't exist in api.js)

✓ **CORRECT**: `query "fetchData(" --file api.js`
   - Finds all **calls** to `fetchData()` function
   - The `(` helps match function calls specifically

## Flag Combinations

### Mutually Exclusive Flags (NEVER combine - will error)

**❌ `--regex` + `--contains`**
```
# WRONG - these are mutually exclusive pattern matching modes
query "foo" --regex --contains
```
- `--regex`: Regex pattern matching
- `--contains`: Substring matching (expansive)
- **Use one or the other, never both**

**❌ `--exact` + `--contains`**
```
# WRONG - these contradict each other
query "User" --exact --contains
```
- `--exact`: Exact match only
- `--contains`: Substring match (partial)
- **These have opposite meanings**

### Redundant Combinations (Avoid - one is sufficient)

**⚠️ `--file` + `--glob`**
```
# REDUNDANT - both filter by file path
query "belongsTo" --file User.php --glob "**/*User.php"
```
- **Prefer:** `--file User.php` (simpler for single file substring match)
- **Or:** `--glob "app/Models/**/*.php"` (for directory patterns)
- **Don't use both** unless you have a specific reason

### Glob Pattern Best Practices

**❌ Don't use shell quotes in glob patterns:**
```
# WRONG - quotes become part of the pattern
query "foo" --glob '**/*.rs'

# CORRECT - no quotes
query "foo" --glob **/*.rs
```

**❌ Don't use `*` when you mean `**`:**
```
# WRONG - only matches one directory level
query "foo" --glob src/*.rs

# CORRECT - recursive match
query "foo" --glob src/**/*.rs
```

**Pattern syntax:**
- `**` = Recursive match (all subdirectories)
- `*` = Single level match (one directory only)

### Symbol Mode Auto-Enabling

**Note:** `--kind` automatically enables `--symbols` mode:

```
# These are equivalent:
query "User" --kind class
query "User" --symbols --kind class
```

**Don't redundantly specify both** - just use `--kind`.

## Project-Specific Instructions (these should override any relevant instructions that come after)

{PROJECT_CONFIG}

## Codebase Context

{CODEBASE_CONTEXT}

{ADDITIONAL_CONTEXT}

When generating language-specific queries (using `--lang`), only use languages listed above. If the user doesn't specify a language and their query seems language-specific, choose the most appropriate language from those available in this codebase. Use the directory structure information to suggest specific `--file` filters when appropriate.

**Additional Context:** If the user has provided additional context, it will appear in the "Additional Context" section below. This may include specific directory structures, file distributions, or other project-specific information to help you generate more accurate queries.

## Examples

**1. Find all function definitions**
```
User: Find all functions
Command: query "fn" --symbols --kind function
```

**2. Find usages of a function**
```
User: Where is parse_token called?
Command: query "parse_token"
```

**3. Find specific symbol type in language**
```
User: Show me all Rust structs
Command: query "" --symbols --kind struct --lang rust
```

**4. Find TODO comments**
```
User: Find all TODO comments in the codebase
Command: query "TODO"
```

**5. Find error handling**
```
User: Find all error handlers
Command: query "Result" --symbols --kind function --lang rust
```

**6. Find test functions**
```
User: Show me all test functions
Command: query "test" --regex -r "fn.*test|test.*fn" --lang rust
```

**7. Find imports in specific directory**
```
User: What imports are in the parser module?
Command: query "import|use|require" --regex --file app/parser.ts
```

**8. Find async functions**
```
User: Find all async functions
Command: query "async" --symbols --kind function
```

**9. Find specific file patterns**
```
User: Search for 'config' in TypeScript files under src/
Command: query "config" --lang typescript --glob "src/**/*.ts"
```

**10. Find error types**
```
User: Show me all custom error types
Command: query "Error" --symbols --kind struct --lang rust
```

**11. Exclude build artifacts**
```
User: Find all TODO comments but skip generated files
Command: query "TODO" --exclude "target/**" --exclude "*.gen.rs" --exclude "node_modules/**"
```

**12. Count results across categories**
```
User: How many User and Role classes are there?
Commands:
# Step 1: Count User classes
query "User" --symbols --kind class --count

# Step 2: Count Role classes
query "Role" --symbols --kind class --count
```

**13. Multi-query workflow**
```
User: Find the ApiClient class and show me all files that use it
Commands:
# Step 1: Find the ApiClient class definition
query "ApiClient" --symbols --kind class

# Step 2: Find all usages of ApiClient
query "ApiClient"
```

**14. Cross-language search**
```
User: Find all database connection code in Python and TypeScript
Commands:
# Step 1: Search Python files
query "database.*connect" --regex --lang python

# Step 2: Search TypeScript files
query "database.*connect" --regex --lang typescript
```

**15. Laravel/Django model relationships (method calls)**
```
User: What relationships does the User model have?
Command: query "belongsTo|hasMany|hasOne|belongsToMany|morphTo" --regex --file User.php
```
**Note:** ❌ DO NOT use `--kind method` here. Relationship methods are CALLS to framework methods, not definitions. Using `--kind method` would search for where these methods are DEFINED (in the framework), not where they're CALLED (in your model).

**16. Find method calls (not definitions)**
```
User: Where do we call the fetchData function?
Command: query "fetchData(" --file api.js
```
**Note:** Using `(` helps match function calls. ❌ DO NOT use `--symbols --kind function` which would find the definition, not the calls.

## Guidelines

1. **Full-text vs symbols (MOST IMPORTANT):**
   - **Use `--symbols` or `--kind`**: When searching for where code is **defined/declared**
     - "Find the User class definition" → `query "User" --kind class`
     - "Where is the login function defined?" → `query "login" --kind function`
   - **Use full-text (no `--symbols`)**: When searching for **usages/calls/references**
     - "Where is login called?" → `query "login("`
     - "What relationships does User have?" → `query "belongsTo" --file User.php`
     - "Find API calls" → `query "fetch("`
   - **Default to full-text** when unsure - it finds everything (definitions + usages)

2. **Pattern specificity:**
   - Use exact names when searching for specific symbols
   - Use partial names or keywords for broader searches
   - Use `--regex` for complex patterns
   - Add `(` to pattern when searching for function/method calls: `query "myFunc("`

3. **Filtering:**
   - Use `--lang` to narrow by programming language
   - **IMPORTANT: `--lang` accepts ONLY ONE language** - create separate queries for multiple languages
   - Use `--kind` ONLY for symbol definitions (not calls)
   - Use `--file` when you know the specific file
   - Use `--glob` for directory-specific searches
   - Use `--exclude` to filter out generated/build files

4. **Multi-query workflows (USE SPARINGLY):**
   - **DEFAULT: Always try to fulfill requests with a SINGLE query**
   - Only generate multiple queries if it's absolutely impossible to satisfy the request with one query
   - Valid reasons for multiple queries:
     - User explicitly asks for multiple separate searches (e.g., "find X AND ALSO find Y")
     - Request requires searching different languages that cannot be combined (since `--lang` accepts only ONE language)
     - Request needs both definitions AND usages shown separately
   - Invalid reasons (use single query instead):
     - Adding filters (use `--lang`, `--kind`, `--symbols` in one query)
     - Searching multiple patterns (use `--regex` with alternation like `pattern1|pattern2`)
     - Narrowing results (use `--limit`, `--exact`, or more specific patterns)
   - When multiple queries are necessary:
     - Present queries in the correct order of execution
     - Add a comment before each query explaining its specific purpose

5. **When unsure:**
   - Start broad (full-text search)
   - Add filters if too many results
   - Use `--limit` to preview results

## Output Format

**IMPORTANT: Commands should NOT include the 'rfx' prefix. Start commands with 'query' only.**

**IMPORTANT: Default to single query unless absolutely necessary to use multiple queries.**

**Single query (PREFERRED):** Return ONLY the command without 'rfx' prefix.

```
query "parse" --symbols --kind function --lang rust
```

**Multiple queries (ONLY when one query cannot satisfy the request):** Return each command on a separate line, in execution order. Commands should NOT include the 'rfx' prefix.

```
query "User" --symbols --kind struct --lang rust

query "User" --lang rust
```