search_content

Find patterns in FULL file content — the whole file, not only the text that belongs to a definition.

Searches ifdef-filtered file text — only code that actually compiles for the build of the query. Inactive #ifdef branches are replaced with blank lines (preserving original line numbers). A pattern that lives only in a dead branch therefore gives no result, and that empty answer is the correct one: the code does not compile.

Covers the text that belongs to no definition, which is what search_bodies cannot see: #include, #define, #ifdef, extern "C", and a comment or declaration at file scope. It covers the text of definitions too. To find a symbol by NAME (modem init, interrupt handler), use search_code.

Not a fallback of search_bodies — its complement. The two answer different questions and reach different text:

• search_bodies answers WHICH DEFINITION holds the pattern, and takes the query literally (no wildcard, space = AND).

• search_content answers WHICH FILES the topic touches, and widens the query: every term gets a trailing * and the terms are OR-joined. The wider query reaches text the literal one misses — measured on one project, SELF_TEST found 6 files here and the same word found 5 through search_bodies, the extra file holding the comment Self tester.

For the footprint of one feature, run both.

Results are file-level — one entry per matching file, with match_lines for the lines that hold a query term. project_only=True filters to is_project = 1 files; the default False includes the vendor SDK files.

When files_fts is missing (legacy index), falls back to LIKE search on files.content — results include _fallback: "like" and no snippet highlighting. Run fw-context index to upgrade. The LIKE search splits the query on spaces and underscores and needs EVERY word as a substring (AND, not OR).

Read-only: yes. Requires the FTS5 index with file content. May auto-reindex stale files (non-blocking) — see search_code.

Args: query: FTS5 search terms. 1-3 words. Bare multi-word queries are OR-joined (prefix-wildcarded). Prefer single-word queries. E.g. 'InterruptIn', 'extern C', '#define'. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results of one page (default 20, max 100). offset: Skip this many results. Reads the next page of a topic that many files touch; the page notice names the offset to use. project_only: When True, filter to project code only (files with is_project = 1). variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.

Returns: list of dicts. The page notice leads the answer — total, offset, shown, more — and each that follows holds: file, language, mtime, _match_snippet (highlighted excerpt around the match).

Also, when it carries an answer:

* ``match_lines`` (list[int]) — line numbers of the lines that hold
  a query term, up to 20.  They are the line numbers of the file
  itself: an inactive ``#ifdef`` branch is a blank line, thus the
  count never shifts.  Cite ``file:line`` from here.

  The field is absent when FTS5 matched a variant of the token that
  the term is not a substring of — ``SELF_TEST`` matches the file
  that writes ``Self tester``, and no line holds ``self_test``.
  Read ``_match_snippet`` in that case.

No match gives ``[]``.  A dict with ``error`` means the query
failed.  A query that FTS5 refuses to parse prepends a dict with
``warning`` + ``hint`` — the answer then comes from the LIKE path
and carries ``_fallback: "like"``.  When a file that the answer
names changed on disk, a dict with ``warning`` comes first; an
empty answer gets it too when indexed files changed.