Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6# Search Functionality Guide
7 
8This guide explains how the search system works in Script Kit based on comprehensive test coverage analysis.
9 
10## Core Files
11 
12- **Main Implementation**: [src/main/search.ts](mdc:src/main/search.ts)
13- **Test Coverage**: [src/main/search.test.ts](mdc:src/main/search.test.ts)
14- **Helper Functions**: [src/main/helpers.ts](mdc:src/main/helpers.ts)
15 
16## Main Search Functions
17 
18### `invokeSearch(prompt, input, reason?)`
19 
20The primary search function that handles choice filtering, searching, and grouping.
21 
22**Key Behaviors:**
23- Returns early if UI is not `arg` type or choices array is empty
24- Transforms input using `inputRegex` if set (extracts match groups)
25- For empty input: shows non-filtered choices (excludes `miss`, `pass`, `hideWithoutInput`)
26- For non-empty input: uses QuickScore for fuzzy search with fallback to manual string matching
27 
28**Choice Type Handling:**
29- **Info choices**: Treated as regular choices, always shown for empty input
30- **Miss choices**: Only shown in fallback when no regular choices exist
31- **Pass choices**: Excluded from regular results, shown in fallback
32- **hideWithoutInput choices**: Only shown when input is not empty
33 
34**Grouping Logic:**
35- Uses complex grouping when `hasGroup` is true
36- Creates "Exact Match" group headers for grouped results
37- Handles `lastGroup` choices separately at the end
38- Supports alias and trigger matching with special group headers
39 
40### `invokeFlagSearch(prompt, input)`
41 
42Handles flag-specific search functionality.
43 
44**Behaviors:**
45- For empty input: filters out `pass`, `hideWithoutInput`, `miss` flags
46- Supports grouped flag search with match headers
47- Falls back to miss flags when no results found
48 
49### `setFlags(prompt, flags)`
50 
51Configures flag choices and sets up flag search.
52 
53**Process:**
541. Converts flag object to choice array format
552. Applies grouping if any flags have groups
563. Formats choices and sets up QuickScore instance
574. Triggers initial flag search
58 
59### `setShortcodes(prompt, choices)`
60 
61Manages shortcodes, keywords, triggers, and postfixes.
62 
63**Important Implementation Details:**
64- **Bug**: Keywords map is NOT cleared (only shortcodes, triggers, postfixes are cleared)
65- **Keywords**: Only processes `choice.keyword` property, not `tag`
66- **Triggers**: Extracts from `choice.trigger` or parses `[trigger]` from choice name
67- **Postfixes**: Only string `pass` values that don't start with `/` (not regex)
68- **Shortcodes**: Case-insensitive storage
69 
70### `setChoices(prompt, choices, options)`
71 
72Main function for setting up search choices.
73 
74**Process:**
751. Filters out choices with `exclude: true`
762. Handles caching for main script choices
773. Sets up QuickScore instance with configurable scoring
784. Calls `setShortcodes` to process special choice properties
795. Triggers initial search unless `skipInitialSearch` is true
80 
81## Search Algorithm Details
82 
83### Empty Input Logic
84```
851. Filter choices: exclude miss, pass, hideWithoutInput
862. Include info choices as regular choices
873. If no regular choices found → show miss and info choices as fallback
88```
89 
90### Non-Empty Input Logic
91```
921. Use QuickScore for fuzzy search
932. If grouped: complex grouping with exact match headers
943. If no results: manual string matching across search keys
954. Apply filtering based on choice types (miss, pass, info)
96```
97 
98### Grouping Behavior
99- **startsWithGroup**: Choices whose names start with the search input
100- **includesGroup**: Choices whose names include the search input (but don't start with it)
101- **matchLastGroup**: Choices with `lastGroup: true`, sorted by keyword presence
102- **Exact Match header**: Added when grouped results exist
103 
104## Important Edge Cases
105 
106### Regex Pass Patterns
107- Choices with `pass: '/regex/i'` are tested against input
108- Invalid regex patterns are handled gracefully without throwing
109 
110### Manual String Matching
111- When QuickScore returns no results, fallback to manual searching
112- Searches across all keys defined in `prompt.kitSearch.keys`
113- Creates scored choices with match positions
114 
115### Choice Filtering Priority
116```
117miss choices: only in fallback scenarios
118pass choices: included in fallback
119info choices: treated as regular choices
120hideWithoutInput: only shown when input exists
121```
122 
123## Performance Considerations
124 
125- Uses QuickScore with configurable max iterations (env: `KIT_SEARCH_MAX_ITERATIONS`)
126- Configurable minimum score threshold (env: `KIT_SEARCH_MIN_SCORE`)
127- Debounced search with 100ms delay (`debounceInvokeSearch`)
128- Caches main script choices for performance
129 
130## Testing Coverage
131 
132The search functionality has **39 comprehensive tests** covering all aspects with a focus on realistic testing:
133 
134### Real Implementations Used
135- **QuickScore**: Actual search and scoring algorithms for realistic behavior
136- **Pure utility functions**: formatChoices, groupChoices, createScoredChoice use real implementations
137- **Kit utils**: Most @johnlindquist/kit/core/utils functions run unmodified
138 
139### Strategic Mocking
140- **lodash debounce**: Mocked for immediate execution (testing search logic, not timing)
141- **State management**: Mocked kitCache and kitState for test isolation
142- **External dependencies**: Logging and messages mocked to avoid test noise
143 
144### Test Coverage Areas
145- All main functions and their edge cases
146- Choice type handling and filtering logic (miss, pass, info, hideWithoutInput)
147- Grouping and sorting behaviors (including complex lastGroup logic)
148- Configuration functions (setChoices, setFlags, setShortcodes)
149- Caching and performance optimizations
150- Error handling and fallback scenarios
151 
152This approach provides realistic test behavior while maintaining fast, deterministic tests. Tests assume current implementation is correct and capture actual behavior for safe refactoring.
153 
154## Known Issues
155 
1561. **Keywords map not cleared**: `setShortcodes` doesn't clear the keywords map (potential memory leak)
1572. **Tag property ignored**: Only `keyword` property is processed for keywords, not `tag`
1583. **Complex grouping logic**: The grouping algorithm is quite complex and could benefit from simplification
159 
160This documentation serves as a foundation for understanding the search system before refactoring for cleanliness and reliability.
161