search_code

Find C/C++ symbols by name — searches function/class/enum NAMES.

Searches symbol names, qualified names, signatures, docstrings, and pre-computed name tokens (CamelCase/snake_case split). Does NOT search function bodies — for patterns in code like .attach(, interrupt handler registrations, callback attachments use search_bodies instead.

Use when you know the concept but not the exact name ("interrupt handler", "modem init"). Prefer lookup_symbol when you already know the exact or prefix name.

Results include names, file locations, signatures, and docstrings — the metadata about each symbol, not the symbol's implementation code.

FTS5 syntax:

• init* matches init, init_uart, initialize (trailing wildcard)

• "spi init" matches the exact phrase "spi init"

• Do NOT use underscore in queries — modem_init is split into modem AND init. Write modem init instead.

Progressive relaxation: when the initial FTS5 search returns nothing, the tool automatically broadens the search in up to six steps:

1. FTS5 with kind filter — the original query with the user-provided kind constraint.

2. FTS5 without kind filter — drops the kind constraint (users often guess the wrong kind for a symbol).

3. name_tokens substring match — searches the pre-computed CamelCase/ snake_case token column (e.g. BuildType is indexed as "build type"). Requires at least N‑1 of N query terms to match.

4. Single-term docstring LIKE — when only one query term was given and the token-based steps found nothing, does a raw LIKE over the docstring column to catch terms the FTS5 tokeniser may have missed.

5. Individual term FTS5 — searches each query word separately and merges the results.

6. Macro FTS5 fallback — searches the macros_fts table for matching #define names and values (kind="macro", _fallback="macros_fts").

Results from fallback steps carry _fallback indicating which method succeeded ("fts5", "name_tokens_like", "docstring_like", "individual_terms", "macros_fts").

Kind filter values: function, method, constructor, destructor, class, struct, union, enum, enum_constant, typedef, variable, field, namespace.

Each result may include summary, inputs, outputs when LLM analysis has been generated (fw-context index --analyze). These provide structured descriptions: what the symbol does, what parameters/data it receives, and what it returns/produces.

Read-only. No side effects.

Args: query: FTS5 search terms. Keep queries short — 1–3 words. project_root: Project root directory. Auto-detected from CWD if omitted. kind: Optional filter to return only symbols of this kind. limit: Maximum results (default 20, max 100). project_only: When True, exclude vendor SDK directories and return only application code. Default False.

Returns: list of dicts, each with: name, qualified_name, kind, file, line, is_definition, signature, docstring, is_template, is_virtual, is_pure_virtual. Enum constants include enum_value with the integer value. May also include template_usr, parent_usr, summary, inputs, outputs when available. Fallback results include _fallback with the method name.