v0.9.0: #ifdef/config-guard awareness — the headline capability

Roadmap milestone 3. Kernel and firmware code defines the same symbol
multiple times under #if/#ifdef and lets the build config pick one; no
other no-build tool tells an agent which definition is live. Now every
definition-shaped result carries its enclosing conditional stack, and
results can be filtered by an actual kernel .config.

- New gtags_mcp.guards module: pure-Python preprocessor-directive
  scanner (comment-aware, continuation-aware, include-guard
  suppression, #elif chains composed into explicit conditions), a
  kernel .config / macro-list parser with kbuild autoconf semantics
  (=m defines CONFIG_X_MODULE; IS_ENABLED/IS_BUILTIN/IS_MODULE), and a
  tri-state expression evaluator. Stat-validated LRU cache (4096
  entries — active_config scans every file a hot symbol touches).
- The guard record field reserved in v0.8.0 is now live: a list of
  conditions outermost-first ([] = unconditional, null = disabled).
  Attached on find_definition, find_references, list_file_symbols, and
  symbol_info.
- symbol_info explains multiply-defined symbols: "N definitions under
  M distinct guards", each with a [CONFIG_X] prefix; new guard_variants
  JSON key.
- active_config on find_definition/find_references/symbol_info: a
  .config path or macro list ("CONFIG_SMP,!CONFIG_DEBUG") drops results
  whose guard stack is DEFINITELY false — unknown macros never drop
  anything; drop count reported as config_filtered (filtering runs
  pre-pagination so totals stay honest).
- Opt out with --no-guards, GTAGS_MCP_GUARDS=0, or guards = false;
  doctor reports guard-scanning status.

Verified on the Linux kernel: kmap resolves to its CONFIG_HIGHMEM /
!CONFIG_HIGHMEM alternates, __efiapi's 3-way #elif chain composes
correctly, a mini .config narrows both to the live definition, and
include-guard suppression keeps ordinary headers noise-free.
81 new tests (178 total).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: harshithsunku

README.md

@@ -163,6 +163,7 @@ bin_dir = "/opt/tools/bin"    # extra directory searched for gtags/global/ctags
 skip_globs = ["*.gen.c"]      # never index paths/basenames matching these globs
 respect_gitignore = true      # default: index only what `git ls-files` reports
 enrich = true                 # default: ctags kind/signature/scope on results
+guards = true                 # default: #ifdef guard stacks on results
 # root = "/abs/path"          # default project root (user config)
 ```
 
@@ -178,7 +179,7 @@ Precedence: tool-call argument > CLI flag > environment variable > project confi
 
 | Tool | What the agent gets |
 |---|---|
-| `symbol_info` | **A one-shot overview card** — definitions (with kind, signature, and scope), reference count, hottest files, and which tool to use next. The best first query for any unfamiliar symbol. |
+| `symbol_info` | **A one-shot overview card** — definitions (with kind, signature, scope, and `#ifdef` guard), reference count, hottest files, and which tool to use next. Multiply-defined symbols are explained as "N definitions under M distinct guards". The best first query for any unfamiliar symbol. |
 | `get_symbol_body` | **Just the source of a definition.** The 271-line `tcp_v4_rcv` function — not the 3,500-line file it lives in. Handles functions, structs, and multi-line macros. |
 | `find_callers` | **The call graph, deduplicated.** Every reference mapped to its enclosing function with call counts: 245 raw lines for `ext4_mark_inode_dirty` collapse to 62 callers. |
 | `call_hierarchy` | **Multi-level impact analysis.** Who calls X, who calls *those*, up to 5 levels — a cycle-safe, capped tree instead of N rounds of grep. |
@@ -225,19 +226,52 @@ Since v0.8.0 every tool returns a **machine-readable JSON envelope by default**
   "tool": "find_definition",
   "root": "/abs/project/root",
   "results": [
-    {"symbol": "tcp_v4_rcv", "path": "net/ipv4/tcp_ipv4.c", "line": 2001,
-     "col": 5, "kind": "function", "typeref": "int", "scope": null,
-     "signature": "(struct sk_buff * skb)", "guard": null,
-     "snippet": "int tcp_v4_rcv(struct sk_buff *skb)"}
+    {"symbol": "kmap", "path": "include/linux/highmem-internal.h", "line": 40,
+     "col": 22, "kind": "function", "typeref": "void *", "scope": null,
+     "signature": "(struct page * page)", "guard": ["CONFIG_HIGHMEM"],
+     "snippet": "static inline void *kmap(struct page *page)"}
   ],
-  "total": 1, "offset": 0, "truncated": false,
+  "total": 2, "offset": 0, "truncated": false,
   "next_tools": ["get_symbol_body", "find_callers", "symbol_info"],
   "warning": null
 }
 ```
 
-- Symbol locations always use the stable record schema `{symbol, path, line, col, kind, typeref, scope, signature, guard, snippet}` with repo-relative paths. Keys are only ever added, never renamed or removed — parsers never need to change shape. `guard` (`#ifdef` stack) is reserved for an upcoming milestone and currently `null`.
+- Symbol locations always use the stable record schema `{symbol, path, line, col, kind, typeref, scope, signature, guard, snippet}` with repo-relative paths. Keys are only ever added, never renamed or removed — parsers never need to change shape.
 - **`kind` / `typeref` / `scope` / `signature` say *what* a symbol is** (since v0.8.1): function vs. macro vs. struct vs. typedef vs. enum constant, its return/target type, its enclosing scope (`enum:color`, `struct:item`), and its parameter list — extracted per file by universal-ctags with **no build and no compile database**, cached, and filled on definition-shaped results (`find_definition`, `symbol_info`, `list_file_symbols`). When universal-ctags isn't available the fields are simply `null`; disable explicitly with `--no-enrich`, `GTAGS_MCP_ENRICH=0`, or `enrich = false` in `.gtags-mcp.toml`.
+- **`guard` says *when* a symbol exists** (since v0.9.0): the enclosing `#if`/`#ifdef` stack, outermost first (`[]` = unconditional, `null` = scanning disabled or file unreadable). See the next section — this is the headline feature.
+
+### `#ifdef`-aware: know which definition your config actually compiles
+
+Kernel and firmware code defines the same symbol multiple times and lets the
+build configuration pick one. Every other no-build tool returns a flat,
+unexplained list — an agent happily reads the no-op stub of `kmap` and
+reasons its way to a wrong answer. This server reads the preprocessor
+conditionals (pure scanning — still no build, no `compile_commands.json`):
+
+```text
+Symbol: kmap
+  2 definitions under 2 distinct guards:
+  [CONFIG_HIGHMEM] defined at include/linux/highmem-internal.h:40 — function kmap(struct page * page) -> void *
+  [!CONFIG_HIGHMEM] defined at include/linux/highmem-internal.h:170 — function kmap(struct page * page) -> void *
+```
+
+Pass `active_config` — a kernel `.config` path or a macro list like
+`"CONFIG_SMP,BITS_PER_LONG=64,!CONFIG_DEBUG"` — to `find_definition`,
+`find_references`, or `symbol_info`, and definitions whose guard stack is
+**definitely false** under it are dropped (the envelope reports the count as
+`config_filtered`). Filtering is deliberately conservative: a `.config` is a
+closed world for `CONFIG_*` macros (kbuild semantics, including
+`=m` → `CONFIG_X_MODULE` and `IS_ENABLED`/`IS_BUILTIN`/`IS_MODULE`), but
+anything unknown (`__ASSEMBLY__`, `ARCH_HAS_*`, arithmetic it can't decide)
+never drops a result.
+
+The details are handled so the output stays clean: classic include guards
+(`#ifndef FOO_H`) are detected and suppressed, `#elif` chains compose into
+explicit conditions (`!CONFIG_X86_64 && CONFIG_X86_32`), comments on
+directives are ignored (they lie), and broken/partial files never fail a
+query. Disable with `--no-guards`, `GTAGS_MCP_GUARDS=0`, or `guards = false`
+in `.gtags-mcp.toml`.
 - `next_tools` tells the agent the highest-value follow-up call for what was (or wasn't) found.
 - `total`/`offset`/`truncated` replace the text continuation footer; errors keep the envelope with an `error` field.
 - Composite tools return tool-shaped `results` (e.g. `call_hierarchy` a nested caller tree, `find_callees` `{in_tree, external}`, `symbol_info` an overview object) inside the same envelope.
@@ -328,10 +362,11 @@ Release flow: bump `version` in `pyproject.toml`, tag `vX.Y.Z`, push — CI publ
 
 ## Roadmap
 
-See [ROADMAP.md](ROADMAP.md) — structured JSON output landed in v0.8.0 and ctags
-metadata enrichment (kind/signature/scope on every definition) in v0.8.1; next up are
-`#ifdef`/config-guard awareness (the headline capability for kernel and firmware
-trees), macro-family symbol resolution, and a correctness eval harness.
+See [ROADMAP.md](ROADMAP.md) — structured JSON output landed in v0.8.0, ctags
+metadata enrichment (kind/signature/scope) in v0.8.1, and `#ifdef`/config-guard
+awareness (the headline capability for kernel and firmware trees) in v0.9.0;
+next up are macro-family symbol resolution, agent workflow tools
+(`reachability`, `blast_radius`), and a correctness eval harness.
 
 Contributions welcome — open an issue or PR.
 

ROADMAP.md

@@ -55,15 +55,15 @@ Cheap, high-value — uses the parser already in the stack.
 
 **Done when:** `symbol_info` shows kind + signature + scope for C symbols with no build.
 
-### 3. `#ifdef` / config-guard awareness — headline capability
+### 3. `#ifdef` / config-guard awareness — headline capability ✅ (v0.9.0)
 The differentiator. Firmware and kernel code is conditional-compilation soup, and
 nothing else surfaces it. Worth spending real time here.
 
-- [ ] For each definition/reference, collect the enclosing
+- [x] For each definition/reference, collect the enclosing
       `#if` / `#ifdef` / `#ifndef` / `#elif` stack and attach it as a `guard` field.
-- [ ] When a symbol has multiple definitions, report them explicitly as
+- [x] When a symbol has multiple definitions, report them explicitly as
       "N definitions under different guards" rather than a flat list.
-- [ ] Add an optional `active_config` filter (a `.config` or a list of defined macros)
+- [x] Add an optional `active_config` filter (a `.config` or a list of defined macros)
       that keeps only definitions whose guard stack is satisfiable.
 
 **Done when:** a multiply-defined symbol returns each definition tagged with its guard

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-gtags-server"
-version = "0.8.2"
+version = "0.9.0"
 description = "Indexed code navigation for AI coding agents — replace grep scans with GNU Global (gtags) lookups over MCP. ~100x faster and radically less noise on million-line C/C++ codebases."
 readme = "README.md"
 requires-python = ">=3.10"

src/gtags_mcp/__init__.py

@@ -1,3 +1,3 @@
 """MCP server exposing GNU Global (gtags) code navigation for C/C++ codebases."""
 
-__version__ = "0.8.2"
+__version__ = "0.9.0"

src/gtags_mcp/config.py

@@ -21,6 +21,7 @@
     skip_globs = ["*.gen.c", "third_party/*"]  # never index matching paths
     respect_gitignore = true        # use `git ls-files` to honour .gitignore
     enrich = true                   # ctags kind/signature/scope on results
+    guards = true                   # #ifdef guard stacks on results
 """
 
 from __future__ import annotations
@@ -37,7 +38,7 @@
 PROJECT_CONFIG_NAME = ".gtags-mcp.toml"
 
 _VALID_KEYS = frozenset(
-    {"root", "label", "bin_dir", "skip_globs", "respect_gitignore", "enrich"}
+    {"root", "label", "bin_dir", "skip_globs", "respect_gitignore", "enrich", "guards"}
 )
 
 # Caches: project configs keyed by directory, user config loaded once.