rename feign_client role to client and add http_client capability (#33)

Switch Feign role inference and flow/ranking role literals to CLIENT, add HTTP_CLIENT capability detection for @FeignClient, and update docs/tool enums to reflect ontology version 9 vocabulary. Add focused rename regression coverage for graph role/capability behavior and brownfield warn-and-drop/acceptance paths.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

CODEBASE_REQUIREMENTS.md

@@ -143,7 +143,7 @@ Roles are assigned **first hit wins** from the type's annotations
 | `@Component` | `COMPONENT` |
 | `@Configuration` | `CONFIG` |
 | `@Entity`, `@MappedSuperclass`, `@Embeddable` | `ENTITY` |
-| `@FeignClient` | `FEIGN_CLIENT` |
+| `@FeignClient` | `CLIENT` (+ capability `HTTP_CLIENT`) |
 | `@Mapper` | `MAPPER` |
 
 **Recommendations:**
@@ -159,8 +159,10 @@ Roles are assigned **first hit wins** from the type's annotations
   `@CodebaseRole` (see `README.md`).
 - **Annotate Feign clients with `@FeignClient`.** This is a
   **class-level** annotation; manually-coded HTTP clients (raw
-  `RestTemplate`/`WebClient` wrappers) won't get the `FEIGN_CLIENT`
-  boost. Consider switching to Feign or extending the role table.
+  `RestTemplate`/`WebClient` wrappers) won't auto-promote to
+  `CLIENT`/`HTTP_CLIENT`; use brownfield annotations
+  (`@CodebaseRole(CodebaseRoleKind.CLIENT)` +
+  `@CodebaseCapability(CodebaseCapabilityKind.HTTP_CLIENT)`) when needed.
 - **JAX-RS resources** (`@Path`, `@GET`, ...) are not recognised as
   `CONTROLLER` out of the box. Add them to the role table
   (Section B.1) or use a brownfield / `@CodebaseRole` override if you
@@ -343,8 +345,8 @@ ROLE_ANNOTATIONS: dict[str, str] = {
     "Entity": "ENTITY",
     "MappedSuperclass": "ENTITY",
     "Embeddable": "ENTITY",
-    "FeignClient": "FEIGN_CLIENT",
-    "RegisterRestClient": "FEIGN_CLIENT", # MicroProfile RestClient
+    "FeignClient": "CLIENT",
+    "RegisterRestClient": "CLIENT", # MicroProfile RestClient
     "Mapper": "MAPPER",
 }
 ```

README.md

@@ -103,6 +103,9 @@ Resolution order for `microservice`:
 > 5. **`ontology_version` 8** adds `GraphMeta.cross_service_resolution` (from
 >    `cross_service_resolution` in `.lancedb-mcp.yml`) — rebuild the Kuzu graph
 >    (`build_ast_graph.py` or `refresh_code_index`) after upgrading.
+> 6. **`ontology_version` 9** renames role `FEIGN_CLIENT` to `CLIENT` and adds
+>    capability `HTTP_CLIENT` for `@FeignClient` interfaces — rebuild to refresh
+>    stored role/capability literals.
 >
 > Any index built before these changes must be rebuilt via
 > `cocoindex update ... --full-reprocess -f` or `refresh_code_index`. Until
@@ -134,7 +137,7 @@ The DB is dropped and rebuilt from scratch on each run (Phase 1 is a full rebuil
 | Tool | Purpose |
 |------|---------|
 | `codebase_search` | Vector / hybrid / graph-expanded search. Supports `role`, `module`, `microservice`, `package_prefix` filters, `graph_expand=true` + `expand_depth=1..3` for Kuzu-BFS fusion (RRF), and `context_neighbors=1..2` to attach adjacent chunks as `context_before`/`context_after`. Java hits return `score_components` (`distance`, `hybrid_rrf`, `role_weight`, `symbol_bonus`, `import_penalty`) so callers can see why a row ranked where it did. |
-| `trace_flow` | Behavioural trace from a natural-language query. Seeds via vector search, then walks CONTROLLER -> SERVICE/COMPONENT -> FEIGN_CLIENT/REPOSITORY/MAPPER in the Kuzu graph and returns staged chains. Defaults to `follow_calls=true` (merges DECLARES+CALLS paths with INJECTS/EXTENDS/IMPLEMENTS — structural edges fill `stage_limit` first per hop, CALLS tops up the remainder); set `follow_calls=false` for type-only wiring. Defaults to `exclude_external=true` on that CALLS hop (same external FQN prefixes as `find_callees` / `expand_methods`: discovered types reached via CALLS, not the caller-only filter used by `find_callers`). |
+| `trace_flow` | Behavioural trace from a natural-language query. Seeds via vector search, then walks CONTROLLER -> SERVICE/COMPONENT -> CLIENT/REPOSITORY/MAPPER in the Kuzu graph and returns staged chains. Defaults to `follow_calls=true` (merges DECLARES+CALLS paths with INJECTS/EXTENDS/IMPLEMENTS — structural edges fill `stage_limit` first per hop, CALLS tops up the remainder); set `follow_calls=false` for type-only wiring. Defaults to `exclude_external=true` on that CALLS hop (same external FQN prefixes as `find_callees` / `expand_methods`: discovered types reached via CALLS, not the caller-only filter used by `find_callers`). |
 | `list_code_index_tables` | Lance tables + Kuzu graph metadata. |
 | `refresh_code_index` | Rebuild LanceDB + Kuzu graph. |
 | `find_implementors` | Classes implementing an interface. |
@@ -208,7 +211,7 @@ Java hits are reweighted after vector / hybrid scoring by their `role`:
 |------|--------|
 | `CONTROLLER` | +0.10 |
 | `SERVICE` | +0.08 |
-| `FEIGN_CLIENT` | +0.06 |
+| `CLIENT` | +0.06 |
 | `COMPONENT` | +0.03 |
 | `REPOSITORY` | +0.02 |
 | `MAPPER` / `OTHER` | 0 |
@@ -232,6 +235,7 @@ A type can carry zero or many capabilities. Capabilities never
 |---|---|
 | `MESSAGE_LISTENER` | `@KafkaListener`, `@RabbitListener`, `@JmsListener`, `@SqsListener`, `@EventListener`, `@StreamListener` on any method |
 | `MESSAGE_PRODUCER` | type injects `KafkaTemplate`, `RabbitTemplate`, `JmsTemplate`, `StreamBridge`, or `ApplicationEventPublisher` |
+| `HTTP_CLIENT` | type has `@FeignClient` |
 | `SCHEDULED_TASK`   | `@Scheduled` on any method, or class implements `org.quartz.Job` |
 | `EXCEPTION_HANDLER`| `@ControllerAdvice`, `@RestControllerAdvice`, or any method with `@ExceptionHandler` |
 
@@ -269,6 +273,11 @@ role_overrides:
 
 Unknown role or capability strings are ignored with a warning on load.
 
+`@FeignClient` interfaces now auto-attach `role=CLIENT` and
+`capability=HTTP_CLIENT`. For `RestTemplate`/`WebClient` wrappers, opt in
+explicitly with `@CodebaseRole(CodebaseRoleKind.CLIENT)` and
+`@CodebaseCapability(CodebaseCapabilityKind.HTTP_CLIENT)`.
+
 **Route overrides (`route_overrides`)** — same `.lancedb-mcp.yml` file; maps
 custom annotation names or qualified names (or suffixes such as `com.acme.Foo`
 when usage sites show only `Foo`) and per-type FQNs to `Route` fields for
@@ -330,11 +339,11 @@ package com.example.rag; // any package
 import java.lang.annotation.*;
 
 public enum CodebaseRoleKind {
-    CONTROLLER, SERVICE, REPOSITORY, COMPONENT, CONFIG, ENTITY, FEIGN_CLIENT, MAPPER, DTO
+    CONTROLLER, SERVICE, REPOSITORY, COMPONENT, CONFIG, ENTITY, CLIENT, MAPPER, DTO
 }
 
 public enum CodebaseCapabilityKind {
-    MESSAGE_LISTENER, MESSAGE_PRODUCER, SCHEDULED_TASK, EXCEPTION_HANDLER
+    MESSAGE_LISTENER, MESSAGE_PRODUCER, HTTP_CLIENT, SCHEDULED_TASK, EXCEPTION_HANDLER
 }
 
 @Target(ElementType.TYPE)

ast_java.py

@@ -70,9 +70,10 @@
     "EqualsAndHashCode", "ToString",
 })
 
-# Phase 5: HTTP_CALLS + ASYNC_CALLS (B2b); Phase 6: cross-service resolution mode on GraphMeta.
+# Phase 5: HTTP_CALLS + ASYNC_CALLS (B2b); Phase 6: cross-service resolution mode on GraphMeta;
+# Phase 7: FEIGN_CLIENT role -> CLIENT + HTTP_CLIENT capability vocabulary cleanup.
 # Bumps whenever extraction / enrichment semantics change.
-ONTOLOGY_VERSION = 8
+ONTOLOGY_VERSION = 9
 
 ROLE_ANNOTATIONS: dict[str, str] = {
     # Spring Web
@@ -88,7 +89,7 @@
     "MappedSuperclass": "ENTITY",
     "Embeddable": "ENTITY",
     # Remoting / messaging
-    "FeignClient": "FEIGN_CLIENT",
+    "FeignClient": "CLIENT",
     # Mappers
     "Mapper": "MAPPER",
 }
@@ -112,6 +113,7 @@
 _TYPE_ANN_TO_CAPABILITY: dict[str, str] = {
     "ControllerAdvice":     "EXCEPTION_HANDLER",
     "RestControllerAdvice": "EXCEPTION_HANDLER",
+    "FeignClient":          "HTTP_CLIENT",
 }
 
 _INJECTED_TYPES_TO_CAPABILITY: dict[str, str] = {

kuzu_queries.py

@@ -994,7 +994,7 @@ def impact_analysis(self, fqn_or_name: str, *, depth: int = 2,
     _FLOW_STAGES: tuple[tuple[str, ...], ...] = (
         ("CONTROLLER",),
         ("SERVICE", "COMPONENT"),
-        ("FEIGN_CLIENT", "REPOSITORY", "MAPPER"),
+        ("CLIENT", "REPOSITORY", "MAPPER"),
     )
 
     # Stage-0 accepts any entrypoint-like role. COMPONENT is included because
@@ -1003,7 +1003,7 @@ def impact_analysis(self, fqn_or_name: str, *, depth: int = 2,
     # orchestrator seeds when the caller already narrowed the vector search
     # to services.
     _ENTRYPOINT_ROLES: tuple[str, ...] = (
-        "CONTROLLER", "COMPONENT", "SERVICE", "FEIGN_CLIENT",
+        "CONTROLLER", "COMPONENT", "SERVICE", "CLIENT",
     )
 
     def trace_flow(self, seed_fqns: list[str], *,
@@ -1013,7 +1013,7 @@ def trace_flow(self, seed_fqns: list[str], *,
                    follow_calls: bool = True,
                    min_call_confidence: float = 0.0,
                    exclude_external: bool = True) -> list[list[StageSymbol]]:
-        """Walk stages `CONTROLLER -> SERVICE/COMPONENT -> FEIGN_CLIENT/REPOSITORY/MAPPER`.
+        """Walk stages `CONTROLLER -> SERVICE/COMPONENT -> CLIENT/REPOSITORY/MAPPER`.
 
         Returns a list of stages; each stage is a list of SymbolHit. The first
         stage is the seed set (entrypoints matched by FQN, filtered to

search_lancedb.py

@@ -185,7 +185,7 @@ def coerce_position_field(val: object) -> dict[str, object]:
 _ROLE_SCORE_WEIGHTS: dict[str, float] = {
     "CONTROLLER": 0.10,
     "SERVICE": 0.08,
-    "FEIGN_CLIENT": 0.06,
+    "CLIENT": 0.06,
     "COMPONENT": 0.03,
     "REPOSITORY": 0.02,
     "MAPPER": 0.00,

server.py

@@ -42,11 +42,11 @@
     "impact_analysis / neighbors / list_by_role / list_by_annotation / list_by_capability for "
     "exact structural traversal. "
     "Use list_by_capability for behavioural questions about message-driven "
-    "(MESSAGE_LISTENER|MESSAGE_PRODUCER), scheduled (SCHEDULED_TASK), or "
+    "(MESSAGE_LISTENER|MESSAGE_PRODUCER), HTTP integration (HTTP_CLIENT), scheduled (SCHEDULED_TASK), or "
     "exception-handling (EXCEPTION_HANDLER) code. "
-    "Use trace_flow for CONTROLLER -> SERVICE -> REPOSITORY/FEIGN end-to-end chains; "
+    "Use trace_flow for CONTROLLER -> SERVICE -> REPOSITORY/CLIENT end-to-end chains; "
     "its seeds are auto-filtered to entrypoint-like roles (CONTROLLER / COMPONENT / "
-    "SERVICE / FEIGN_CLIENT), so it's the right tool for 'how / what happens when' queries. "
+    "SERVICE / CLIENT), so it's the right tool for 'how / what happens when' queries. "
     "trace_flow defaults to follow_calls=true (DECLARES+CALLS plus cross-service HTTP_CALLS/ASYNC_CALLS "
     "paths merged with INJECTS/EXTENDS/"
     "IMPLEMENTS) and exclude_external=true on that CALLS hop (drops discovered types under "
@@ -686,13 +686,13 @@ async def codebase_search(
         auto_hybrid: bool = Field(default=False),
         role: str | None = Field(
             default=None,
-            description="Java only: CONTROLLER|SERVICE|REPOSITORY|COMPONENT|CONFIG|ENTITY|FEIGN_CLIENT|MAPPER|DTO",
+            description="Java only: CONTROLLER|SERVICE|REPOSITORY|COMPONENT|CONFIG|ENTITY|CLIENT|MAPPER|DTO",
         ),
         capability: str | None = Field(
             default=None,
             description=(
                 "Java only: AND-filter to chunks whose enclosing type carries "
-                "this capability (MESSAGE_LISTENER|MESSAGE_PRODUCER|"
+                "this capability (MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|"
                 "SCHEDULED_TASK|EXCEPTION_HANDLER). Use `list_by_capability` "
                 "for graph-only queries."
             ),
@@ -856,7 +856,7 @@ async def find_implementors(
         capability: str | None = Field(
             default=None,
             description="Optional: only return symbols also carrying this capability "
-                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|SCHEDULED_TASK|EXCEPTION_HANDLER).",
+                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|SCHEDULED_TASK|EXCEPTION_HANDLER).",
         ),
     ) -> SymbolListOutput:
         ok, graph, msg = _require_graph()
@@ -880,7 +880,7 @@ async def find_subclasses(
         capability: str | None = Field(
             default=None,
             description="Optional: only return symbols also carrying this capability "
-                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|SCHEDULED_TASK|EXCEPTION_HANDLER).",
+                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|SCHEDULED_TASK|EXCEPTION_HANDLER).",
         ),
     ) -> SymbolListOutput:
         ok, graph, msg = _require_graph()
@@ -1138,14 +1138,14 @@ async def trace_request_flow(
         description="All graph symbols with a given role (CONTROLLER|SERVICE|REPOSITORY|...).",
     )
     async def list_by_role(
-        role: str = Field(description="CONTROLLER|SERVICE|REPOSITORY|COMPONENT|CONFIG|ENTITY|FEIGN_CLIENT|MAPPER|OTHER"),
+        role: str = Field(description="CONTROLLER|SERVICE|REPOSITORY|COMPONENT|CONFIG|ENTITY|CLIENT|MAPPER|OTHER"),
         module: str | None = Field(default=None, description="Maven/Gradle module name."),
         microservice: str | None = Field(default=None, description="Microservice name."),
         limit: int = Field(default=100, ge=1, le=500),
         capability: str | None = Field(
             default=None,
             description="Optional: AND-filter to symbols also carrying this capability "
-                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|SCHEDULED_TASK|EXCEPTION_HANDLER).",
+                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|SCHEDULED_TASK|EXCEPTION_HANDLER).",
         ),
     ) -> SymbolListOutput:
         ok, graph, msg = _require_graph()
@@ -1169,7 +1169,7 @@ async def list_by_annotation(
         capability: str | None = Field(
             default=None,
             description="Optional: AND-filter to symbols also carrying this capability "
-                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|SCHEDULED_TASK|EXCEPTION_HANDLER).",
+                        "(MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|SCHEDULED_TASK|EXCEPTION_HANDLER).",
         ),
     ) -> SymbolListOutput:
         ok, graph, msg = _require_graph()
@@ -1185,15 +1185,15 @@ async def list_by_annotation(
         name="list_by_capability",
         description=(
             "All graph symbols carrying a given capability "
-            "(MESSAGE_LISTENER|MESSAGE_PRODUCER|SCHEDULED_TASK|EXCEPTION_HANDLER). "
+            "(MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|SCHEDULED_TASK|EXCEPTION_HANDLER). "
             "Capabilities are derived from method/type annotations and injected "
             "types; a class can carry several. Pair with `list_by_role` for "
             "primary-purpose questions."
         ),
     )
     async def list_by_capability(
         capability: str = Field(
-            description="MESSAGE_LISTENER|MESSAGE_PRODUCER|SCHEDULED_TASK|EXCEPTION_HANDLER",
+            description="MESSAGE_LISTENER|MESSAGE_PRODUCER|HTTP_CLIENT|SCHEDULED_TASK|EXCEPTION_HANDLER",
         ),
         module: str | None = Field(default=None, description="Maven/Gradle module name."),
         microservice: str | None = Field(default=None, description="Microservice name."),
@@ -1335,11 +1335,11 @@ async def graph_meta() -> GraphMetaOutput:
         description=(
             "End-to-end behavioural trace for a natural-language query. "
             "Picks seed entrypoints via vector search (restricted to CONTROLLER / "
-            "COMPONENT / SERVICE / FEIGN_CLIENT roles, plus types carrying "
+            "COMPONENT / SERVICE / CLIENT roles, plus types carrying "
             "MESSAGE_LISTENER or SCHEDULED_TASK capabilities, with a fallback pass "
             "when nothing matches), then walks the Kuzu graph in role-ordered stages "
             "(CONTROLLER/COMPONENT/SERVICE -> SERVICE/COMPONENT -> "
-            "FEIGN_CLIENT/REPOSITORY/MAPPER) and returns the likely chain.\n"
+            "CLIENT/REPOSITORY/MAPPER) and returns the likely chain.\n"
             "Each stage symbol carries `via: [{edge_type, from_fqn, hop}]` so "
             "callers can see *why* it was pulled in (INJECTS / EXTENDS / "
             "IMPLEMENTS / CALLS). Stage 0 is seeds and has `via=[]`.\n"
@@ -1415,7 +1415,7 @@ async def trace_flow(
         if exclude_roles:
             baseline_excludes.update(r.upper() for r in exclude_roles if r)
 
-        entry_roles = ["CONTROLLER", "COMPONENT", "SERVICE", "FEIGN_CLIENT"]
+        entry_roles = ["CONTROLLER", "COMPONENT", "SERVICE", "CLIENT"]
         entry_capabilities = ["MESSAGE_LISTENER", "SCHEDULED_TASK"]
 
         def _seed(role_allowlist: list[str] | None,