reindex_file
Update an edited C/C++ file's symbols in the index without a full rebuild by re-parsing it with compile_commands.json flags.
Instructions
Re-parse a single source file with libclang and update its symbols in the index.
Not read-only — uses the exact compiler flags from compile_commands.json.
Use after editing a file to keep the index current without a full rebuild.
Without variant and image the file is re-parsed in EACH build
of the project that compiles it: an edit on disk changes the file for
every build of the tree. A build that does not compile the file is
named in builds_without_file. With the two arguments of one build,
as get_project_status lists them, only that build is re-parsed; a
part of a pair gets an error that lists the builds.
The call runs in a thread of the server and sends a notice each 5 s.
It holds the lock of the query tools: another query waits 5 s, then
gets "server busy". After 300 s the call returns an error, and a
part of the work can continue or fail. Call get_project_status
for the state of each build, and repeat the call for a build that is
not current. The answer holds no index_state.
A source file must be listed in compile_commands.json. A header is
not listed there — compile_commands.json names translation units — so it
is re-parsed through one unit that includes it, taken from the manifest
of each build. That answer describes a single compilation context,
thus the result carries a warning: another unit can see the header
under a different set of #define values and still hold stale
symbols. Only a full fw-context index covers every context. One
unit and not all of them is a cost decision — an application header
reaches a median of 3 units but as many as 266 on a real project, at
tens of seconds each.
Also rebuilds the method override relationships, the PageRank scores
and the hotspot cache when reference indexing is on
([index] index_refs), with and without with_analysis. When
with_analysis=True and the LLM is on ([llm] enabled), it also
regenerates the LLM analysis and the embeddings of the affected
symbols. The analysis also needs [llm] analyze_symbols. It is
content-addressed, thus an unchanged symbol is never re-analysed.
Args:
file_path: Path to the file to re-parse. A source file must be in
compile_commands.json; a header goes through one including unit.
project_root: Project root directory. 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.
variant: The variant of the one build to re-parse. Omit it, and
image, to re-parse each build that compiles the file.
image: The image of the one build to re-parse.
with_analysis: When True (default), also regenerates the LLM symbol
analysis and the embeddings, which need a model. Set False for a
fast update: the status tools then report the symbols that wait
for the two.
A file that is gone from disk but still in the index has its records removed in each build that holds it; the result is then {file, symbols_removed, action: "deleted", builds}.
Returns:
dict: {file, translation_units, symbols_updated, elapsed_s, builds},
plus builds_without_file when a build does not compile the file.
builds has one entry for each build that compiles the file:
{variant, image, translation_units, symbols_updated, elapsed_s},
plus when they apply: skipped_tus and skipped_count (units that
failed to parse), warning (header coverage), analysis_updated and
embeddings_updated (counts for the whole build, not this file), and
analysis_warning, overrides_warning, pagerank_warning, or
embedding_warning when a phase failed, or error when the
re-parse of that build failed.
When one build compiles the file, the top level holds the full
result of that build. When several do, the top level holds the
sums of the builds that did not fail, ``elapsed_s`` of the whole
call, the sum of ``skipped_count``, ``warning`` only when each of
those builds has it, and ``failed_builds`` with the label of each
build whose entry holds ``error``.
On failure the dict holds ``error`` with the reason: a refusal of
the selector, no build that compiles the file, or an update that
failed in each build. It can add ``skipped_tus`` or ``action``.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Image of the one build to re-parse: a separate program, such as the application or the bootloader. Give it when that build has an image name. | |
| project | No | 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. | |
| variant | No | Variant of the one build to re-parse. Omit it and image to re-parse the file in each build that compiles it. A part of a pair gets an error that lists the builds. | |
| file_path | Yes | Absolute or project-relative path to the file to re-parse. A source file must have an entry in compile_commands.json. A header is re-parsed through one translation unit that includes it, and the result then carries a warning that other units can still hold stale symbols. | |
| project_root | No | Project root directory. Auto-detected from cwd if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. | |
| with_analysis | No | When True (default), also regenerates the LLM symbol analysis and the embeddings — slower, because the two need a model. Set False for a fast update: the tool skips the two, and get_project_status then reports the symbols that wait for them. The method overrides, the PageRank scores and the hotspot cache are rebuilt in the two modes when reference indexing is on (`[index] index_refs`). |