How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

review - Prompt - OpenSmartRoute

Name: review
Author: conradkoh

Prompt file imported from conradkoh/raggrep (.cursor/commands/review.md). Copyright stays with the author.

Index Feature Review Checklist

Review checklist for new indexing features to ensure correctness, performance, and incremental update support.

Instructions

When adding a new index type (like literal index, reference index, etc.), run through this checklist to verify the implementation handles all edge cases correctly.

Pre-Flight Checks

Before reviewing the feature, ensure:

# Run all tests
bun test --timeout 180000

# Run TypeScript type check
bunx tsc --noEmit

Both must pass before proceeding with the review.

1. Index Invalidation & Staleness

File Modification

When a file is modified, old index entries are removed before new ones are added
Renamed identifiers (e.g., foo → bar) don't leave stale entries
Line number changes don't create duplicate entries with different chunk IDs

How to verify:

Index a file with a function testFunc
Rename testFunc to renamedFunc
Re-index
Search for testFunc - should return NO results
Search for renamedFunc - should return the function

File Deletion

When a file is deleted, all its index entries are removed
No orphaned entries remain in secondary indexes (literal, symbolic, etc.)

How to verify:

Index a file with identifiers
Delete the file from disk
Run index again (or cleanup)
Verify the index file JSON is gone
Verify secondary index entries are removed

Chunk ID Stability

Chunk IDs are deterministic (same content = same ID)
Chunk IDs change appropriately when content changes
Index correctly handles chunk ID changes on re-index

2. Incremental Updates

Efficiency

Only modified files are re-indexed (not the entire codebase)
finalize() doesn't rebuild the entire index from scratch
Secondary indexes support incremental updates (add/remove individual entries)

How to verify:

Index a large folder
Modify ONE file
Re-index with --verbose
Verify only 1 file shows as indexed (others show as unchanged)

Data Structures

Index has removeFile(filepath) method for cleanup
Index has removeChunk(chunkId) method for granular cleanup
Both methods properly update all internal data structures

Finalize Hook

Module's finalize() is called after indexing changes
finalize() properly cleans up old data before adding new
finalize() handles the case where some files were deleted

3. Storage & Persistence

File Format

Index is stored in JSON (human-readable, debuggable)
Schema version is included for compatibility checking
Version mismatch triggers appropriate warning or rebuild

Paths

Uses getRaggrepDir() for consistent index location
Filepath keys are relative (not absolute) for portability
Works correctly with the temp directory storage location

Atomic Operations

Index save is atomic (write to temp, then rename)
Partial failures don't corrupt the index
Index can recover from interrupted saves

4. Search Integration

Query Processing

Query terms are properly extracted/parsed
Index is loaded once per search (not per-file)
Search handles missing/empty index gracefully

Result Merging

Results from this index merge correctly with other sources
Scoring is multiplicative or additive as designed
No duplicate results from same chunk

Two-Path Retrieval (if applicable)

Index-only matches are included in results
Properly loads chunks not found by semantic/BM25 search
Base score is applied for index-only matches

5. Performance

Memory

Large indexes don't cause OOM
Index is loaded lazily where possible
Cleared from memory after use

Speed

Index lookup is O(1) or O(log n), not O(n)
Building index doesn't block on I/O unnecessarily
Search latency stays under 500ms for typical queries

Scalability

Tested with 1000+ files
Index size grows linearly (not exponentially) with codebase

6. Edge Cases

Empty/Missing

Handles empty files gracefully
Handles missing index directory (creates it)
Handles corrupted index file (rebuilds)

Special Characters

Handles filenames with spaces
Handles unicode in identifiers
Handles very long identifiers

Concurrent Access

Multiple index processes don't corrupt data
Watch mode handles rapid file changes

Post-Review

After completing the review:

# Run all tests again
bun test --timeout 180000

# Run TypeScript type check
bunx tsc --noEmit

# Run manual sanity check (optional)
cd scenarios/basic
bun run ../../src/app/cli/main.ts index
bun run ../../src/app/cli/main.ts query "your test query" --top 5

Checklist Template

Copy this for PR reviews:

## Index Feature Review

### Pre-flight

- [ ] `bun test` passes
- [ ] `tsc --noEmit` passes

### Invalidation

- [ ] File modification cleans up old entries
- [ ] File deletion removes all entries
- [ ] Chunk IDs handled correctly

### Incremental

- [ ] Only modified files re-indexed
- [ ] Has `removeFile()` method
- [ ] `finalize()` handles cleanup

### Storage

- [ ] JSON format with version
- [ ] Correct paths with `getRaggrepDir()`

### Search

- [ ] Query parsing correct
- [ ] Results merge properly
- [ ] Index-only matches included

### Performance

- [ ] O(1) lookup
- [ ] Tested with large codebase

Common Issues & Fixes

Issue	Symptom	Fix
Stale entries	Old identifiers still found	Add `removeFile()` call in `finalize()`
Full rebuild	Index slow after 1-file change	Check if `finalize()` clears everything
Missing results	Index-only matches not showing	Implement two-path retrieval
Wrong paths	Index not found	Use `getRaggrepDir()` consistently
Type errors	Build fails	Export types from `domain/entities`

# Index Feature Review Checklist Review checklist for new indexing features to ensure correctness, performance, and incremental update support. ## Instructions When adding a new index type (like literal index, reference index, etc.), run through this checklist to verify the implementation handles all edge cases correctly. ## Pre-Flight Checks Before reviewing the feature, ensure: ```bash # Run all tests bun test --timeout 180000 # Run TypeScript type check bunx tsc --noEmit ``` Both must pass before proceeding with the review. ## 1. Index Invalidation & Staleness ### File Modification - [ ] When a file is **modified**, old index entries are removed before new ones are added - [ ] Renamed identifiers (e.g., `foo` → `bar`) don't leave stale entries - [ ] Line number changes don't create duplicate entries with different chunk IDs **How to verify:** 1. Index a file with a function `testFunc` 2. Rename `testFunc` to `renamedFunc` 3. Re-index 4. Search for `testFunc` - should return NO results 5. Search for `renamedFunc` - should return the function ### File Deletion - [ ] When a file is **deleted**, all its index entries are removed - [ ] No orphaned entries remain in secondary indexes (literal, symbolic, etc.) **How to verify:** 1. Index a file with identifiers 2. Delete the file from disk 3. Run index again (or cleanup) 4. Verify the index file JSON is gone 5. Verify secondary index entries are removed ### Chunk ID Stability - [ ] Chunk IDs are deterministic (same content = same ID) - [ ] Chunk IDs change appropriately when content changes - [ ] Index correctly handles chunk ID changes on re-index ## 2. Incremental Updates ### Efficiency - [ ] Only modified files are re-indexed (not the entire codebase) - [ ] `finalize()` doesn't rebuild the entire index from scratch - [ ] Secondary indexes support incremental updates (add/remove individual entries) **How to verify:** 1. Index a large folder 2. Modify ONE file 3. Re-index with `--verbose` 4. Verify only 1 file shows as indexed (others show as unchanged) ### Data Structures - [ ] Index has `removeFile(filepath)` method for cleanup - [ ] Index has `removeChunk(chunkId)` method for granular cleanup - [ ] Both methods properly update all internal data structures ### Finalize Hook - [ ] Module's `finalize()` is called after indexing changes - [ ] `finalize()` properly cleans up old data before adding new - [ ] `finalize()` handles the case where some files were deleted ## 3. Storage & Persistence ### File Format - [ ] Index is stored in JSON (human-readable, debuggable) - [ ] Schema version is included for compatibility checking - [ ] Version mismatch triggers appropriate warning or rebuild ### Paths - [ ] Uses `getRaggrepDir()` for consistent index location - [ ] Filepath keys are relative (not absolute) for portability - [ ] Works correctly with the temp directory storage location ### Atomic Operations - [ ] Index save is atomic (write to temp, then rename) - [ ] Partial failures don't corrupt the index - [ ] Index can recover from interrupted saves ## 4. Search Integration ### Query Processing - [ ] Query terms are properly extracted/parsed - [ ] Index is loaded once per search (not per-file) - [ ] Search handles missing/empty index gracefully ### Result Merging - [ ] Results from this index merge correctly with other sources - [ ] Scoring is multiplicative or additive as designed - [ ] No duplicate results from same chunk ### Two-Path Retrieval (if applicable) - [ ] Index-only matches are included in results - [ ] Properly loads chunks not found by semantic/BM25 search - [ ] Base score is applied for index-only matches ## 5. Performance ### Memory - [ ] Large indexes don't cause OOM - [ ] Index is loaded lazily where possible - [ ] Cleared from memory after use ### Speed - [ ] Index lookup is O(1) or O(log n), not O(n) - [ ] Building index doesn't block on I/O unnecessarily - [ ] Search latency stays under 500ms for typical queries ### Scalability - [ ] Tested with 1000+ files - [ ] Index size grows linearly (not exponentially) with codebase ## 6. Edge Cases ### Empty/Missing - [ ] Handles empty files gracefully - [ ] Handles missing index directory (creates it) - [ ] Handles corrupted index file (rebuilds) ### Special Characters - [ ] Handles filenames with spaces - [ ] Handles unicode in identifiers - [ ] Handles very long identifiers ### Concurrent Access - [ ] Multiple index processes don't corrupt data - [ ] Watch mode handles rapid file changes ## Post-Review After completing the review: ```bash # Run all tests again bun test --timeout 180000 # Run TypeScript type check bunx tsc --noEmit # Run manual sanity check (optional) cd scenarios/basic bun run ../../src/app/cli/main.ts index bun run ../../src/app/cli/main.ts query "your test query" --top 5 ``` ## Checklist Template Copy this for PR reviews: ```markdown ## Index Feature Review ### Pre-flight - [ ] `bun test` passes - [ ] `tsc --noEmit` passes ### Invalidation - [ ] File modification cleans up old entries - [ ] File deletion removes all entries - [ ] Chunk IDs handled correctly ### Incremental - [ ] Only modified files re-indexed - [ ] Has `removeFile()` method - [ ] `finalize()` handles cleanup ### Storage - [ ] JSON format with version - [ ] Correct paths with `getRaggrepDir()` ### Search - [ ] Query parsing correct - [ ] Results merge properly - [ ] Index-only matches included ### Performance - [ ] O(1) lookup - [ ] Tested with large codebase ``` ## Common Issues & Fixes | Issue | Symptom | Fix | | --------------- | ------------------------------ | --------------------------------------- | | Stale entries | Old identifiers still found | Add `removeFile()` call in `finalize()` | | Full rebuild | Index slow after 1-file change | Check if `finalize()` clears everything | | Missing results | Index-only matches not showing | Implement two-path retrieval | | Wrong paths | Index not found | Use `getRaggrepDir()` consistently | | Type errors | Build fails | Export types from `domain/entities` |

{ "prompt": "# Index Feature Review Checklist\n\nReview checklist for new indexing features to ensure correctness, performance, and incremental update support.\n\n## Instructions\n\nWhen adding a new index type (like literal index, reference index, etc.), run through this checklist to verify the implementation handles all edge cases correctly.\n\n## Pre-Flight Checks\n\nBefore reviewing the feature, ensure:\n\n```bash\n# Run all tests\nbun test --timeout 180000\n\n# Run TypeScript type check\nbunx tsc --noEmit\n```\n\nBoth must pass before proceeding with the review.\n\n## 1. Index Invalidation & Staleness\n\n### File Modification\n\n- [ ] When a file is **modified**, old index entries are removed before new ones are added\n- [ ] Renamed identifiers (e.g., `foo` → `bar`) don't leave stale entries\n- [ ] Line number changes don't create duplicate entries with different chunk IDs\n\n**How to verify:**\n\n1. Index a file with a function `testFunc`\n2. Rename `testFunc` to `renamedFunc`\n3. Re-index\n4. Search for `testFunc` - should return NO results\n5. Search for `renamedFunc` - should return the function\n\n### File Deletion\n\n- [ ] When a file is **deleted**, all its index entries are removed\n- [ ] No orphaned entries remain in secondary indexes (literal, symbolic, etc.)\n\n**How to verify:**\n\n1. Index a file with identifiers\n2. Delete the file from disk\n3. Run index again (or cleanup)\n4. Verify the index file JSON is gone\n5. Verify secondary index entries are removed\n\n### Chunk ID Stability\n\n- [ ] Chunk IDs are deterministic (same content = same ID)\n- [ ] Chunk IDs change appropriately when content changes\n- [ ] Index correctly handles chunk ID changes on re-index\n\n## 2. Incremental Updates\n\n### Efficiency\n\n- [ ] Only modified files are re-indexed (not the entire codebase)\n- [ ] `finalize()` doesn't rebuild the entire index from scratch\n- [ ] Secondary indexes support incremental updates (add/remove individual entries)\n\n**How to verify:**\n\n1. Index a large folder\n2. Modify ONE file\n3. Re-index with `--verbose`\n4. Verify only 1 file shows as indexed (others show as unchanged)\n\n### Data Structures\n\n- [ ] Index has `removeFile(filepath)` method for cleanup\n- [ ] Index has `removeChunk(chunkId)` method for granular cleanup\n- [ ] Both methods properly update all internal data structures\n\n### Finalize Hook\n\n- [ ] Module's `finalize()` is called after indexing changes\n- [ ] `finalize()` properly cleans up old data before adding new\n- [ ] `finalize()` handles the case where some files were deleted\n\n## 3. Storage & Persistence\n\n### File Format\n\n- [ ] Index is stored in JSON (human-readable, debuggable)\n- [ ] Schema version is included for compatibility checking\n- [ ] Version mismatch triggers appropriate warning or rebuild\n\n### Paths\n\n- [ ] Uses `getRaggrepDir()` for consistent index location\n- [ ] Filepath keys are relative (not absolute) for portability\n- [ ] Works correctly with the temp directory storage location\n\n### Atomic Operations\n\n- [ ] Index save is atomic (write to temp, then rename)\n- [ ] Partial failures don't corrupt the index\n- [ ] Index can recover from interrupted saves\n\n## 4. Search Integration\n\n### Query Processing\n\n- [ ] Query terms are properly extracted/parsed\n- [ ] Index is loaded once per search (not per-file)\n- [ ] Search handles missing/empty index gracefully\n\n### Result Merging\n\n- [ ] Results from this index merge correctly with other sources\n- [ ] Scoring is multiplicative or additive as designed\n- [ ] No duplicate results from same chunk\n\n### Two-Path Retrieval (if applicable)\n\n- [ ] Index-only matches are included in results\n- [ ] Properly loads chunks not found by semantic/BM25 search\n- [ ] Base score is applied for index-only matches\n\n## 5. Performance\n\n### Memory\n\n- [ ] Large indexes don't cause OOM\n- [ ] Index is loaded lazily where possible\n- [ ] Cleared from memory after use\n\n### Speed\n\n- [ ] Index lookup is O(1) or O(log n), not O(n)\n- [ ] Building index doesn't block on I/O unnecessarily\n- [ ] Search latency stays under 500ms for typical queries\n\n### Scalability\n\n- [ ] Tested with 1000+ files\n- [ ] Index size grows linearly (not exponentially) with codebase\n\n## 6. Edge Cases\n\n### Empty/Missing\n\n- [ ] Handles empty files gracefully\n- [ ] Handles missing index directory (creates it)\n- [ ] Handles corrupted index file (rebuilds)\n\n### Special Characters\n\n- [ ] Handles filenames with spaces\n- [ ] Handles unicode in identifiers\n- [ ] Handles very long identifiers\n\n### Concurrent Access\n\n- [ ] Multiple index processes don't corrupt data\n- [ ] Watch mode handles rapid file changes\n\n## Post-Review\n\nAfter completing the review:\n\n```bash\n# Run all tests again\nbun test --timeout 180000\n\n# Run TypeScript type check\nbunx tsc --noEmit\n\n# Run manual sanity check (optional)\ncd scenarios/basic\nbun run ../../src/app/cli/main.ts index\nbun run ../../src/app/cli/main.ts query \"your test query\" --top 5\n```\n\n## Checklist Template\n\nCopy this for PR reviews:\n\n```markdown\n## Index Feature Review\n\n### Pre-flight\n\n- [ ] `bun test` passes\n- [ ] `tsc --noEmit` passes\n\n### Invalidation\n\n- [ ] File modification cleans up old entries\n- [ ] File deletion removes all entries\n- [ ] Chunk IDs handled correctly\n\n### Incremental\n\n- [ ] Only modified files re-indexed\n- [ ] Has `removeFile()` method\n- [ ] `finalize()` handles cleanup\n\n### Storage\n\n- [ ] JSON format with version\n- [ ] Correct paths with `getRaggrepDir()`\n\n### Search\n\n- [ ] Query parsing correct\n- [ ] Results merge properly\n- [ ] Index-only matches included\n\n### Performance\n\n- [ ] O(1) lookup\n- [ ] Tested with large codebase\n```\n\n## Common Issues & Fixes\n\n| Issue | Symptom | Fix |\n| --------------- | ------------------------------ | --------------------------------------- |\n| Stale entries | Old identifiers still found | Add `removeFile()` call in `finalize()` |\n| Full rebuild | Index slow after 1-file change | Check if `finalize()` clears everything |\n| Missing results | Index-only matches not showing | Implement two-path retrieval |\n| Wrong paths | Index not found | Use `getRaggrepDir()` consistently |\n| Type errors | Build fails | Export types from `domain/entities` |", "variables": [], "notes": "Review checklist for new indexing features to ensure correctness, performance, and incremental update support.", "metadata": { "source": { "provider": "github-cursor-commands", "repository": "https://github.com/conradkoh/raggrep", "path": ".cursor/commands/review.md", "ref": "2e0a21cfb034ed189442fe42f2bf24e3b11b021d", "url": "https://github.com/conradkoh/raggrep/blob/2e0a21cfb034ed189442fe42f2bf24e3b11b021d/.cursor/commands/review.md", "key": "conradkoh/raggrep/.cursor/commands/review.md" } } }

review

About

Index Feature Review Checklist

Instructions

Pre-Flight Checks

1. Index Invalidation & Staleness

File Modification

File Deletion

Chunk ID Stability

2. Incremental Updates

Efficiency

Data Structures

Finalize Hook

3. Storage & Persistence

File Format

Paths

Atomic Operations

4. Search Integration

Query Processing

Result Merging

Two-Path Retrieval (if applicable)

5. Performance

Memory

Speed

Scalability

6. Edge Cases

Empty/Missing

Special Characters

Concurrent Access

Post-Review

Checklist Template

Common Issues & Fixes

Install review and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews