propose: FEIGN_CLIENT role → CLIENT + HTTP_CLIENT capability#28
Merged
Conversation
Add CLIENT-ROLE-RENAME-PROPOSE.md: - Rename role enum FEIGN_CLIENT → CLIENT (Spring-native vocabulary) - Add HTTP_CLIENT capability (peer to MESSAGE_PRODUCER which already exists) - Keep auto-promotion scoped exactly as today (only @FeignClient interfaces) - RestTemplate/WebClient users opt in via brownfield @CodebaseRole annotations - Two-phase deprecation alias: FEIGN_CLIENT accepted as alias for one release - Ships AFTER PR-F1 and PR-G1; ontology bump 8→9 (or 7→8 if order changes) Delete DEFERRED-REST-CLIENT-MIGRATION-PROPOSE.md: - Superseded by the new propose - Its 2026-04-26 conclusion (REST_CLIENT as capability, not role rename) is reversed by this proposal — the architecture has moved on: capabilities already exist, brownfield overrides already exist, and @CodebaseRole already lets users assign primary roles honestly.
MCP bundle has no users yet — breaking changes are explicitly allowed. Simpler, smaller, cleaner: - Remove FEIGN_CLIENT from VALID_ROLES in the same PR (no alias) - Brownfield YAML/annotation inputs that still say FEIGN_CLIENT fail validation via the existing VALID_ROLES check; error message lists allowed roles, redirecting users to CLIENT + HTTP_CLIENT - No new helper code in graph_enrich.py (was ~15 LOC alias machinery) - LOC estimate ~120 → ~105 - Test #4 flipped from 'alias translated' to 'role rejected' - §9 [TBD] reduced from 7 → 5 (alias-specific items removed) - Risks table updated (row 1 likelihood N/A; old row 6 'alias complexity' removed)
This was referenced May 6, 2026
HumanBean17
added a commit
that referenced
this pull request
May 6, 2026
…ty (#32) Implements propose merged in #28. Sequences after PR-F1 (#31, merged) and PR-G1 (#30, merged). Hard rename — no deprecation alias, MCP bundle has no users yet and breaking changes are explicitly allowed. Single PR, ~115 LOC, ontology bump 8→9. Single source-of-truth flips at ast_java.py:91 (role) and ast_java.py:114 (HTTP_CLIENT capability); VALID_ROLES / VALID_CAPABILITIES are auto-derived so no java_ontology.py edit needed. 9 new tests in tests/test_client_role_rename.py target ~290 passed, 4 skipped (281 baseline + 9). Plan delta from propose: test #4 asserts warn-and-drop behaviour (stderr warning + override silently dropped) matching actual graph_enrich.py:443-447, 481-486, NOT raised ValueError as the propose's example suggested. Out of scope: async role/capability changes (MESSAGE_PRODUCER already covers Kafka/Rabbit/JMS), auto-promoting RestTemplate/WebClient to HTTP_CLIENT (brownfield-only opt-in), backwards-compat alias, RegisterRestClient (followup #3).
HumanBean17
added a commit
that referenced
this pull request
May 6, 2026
* chore: tidy completed plans/proposes and refresh stale docs Move completed plans to plans/completed/: - PLAN-CLIENT-ROLE-RENAME.md (PR #33 merged) - PLAN-CROSS-SERVICE-RESOLUTION-FLAG.md (PR #30 merged) - PLAN-FEIGN-NOT-AN-EXPOSER.md (PR #31 merged) Move completed proposes to propose/completed/: - CLIENT-ROLE-RENAME-PROPOSE.md (PR #28 merged) - CROSS-SERVICE-RESOLUTION-FLAG-PROPOSE.md (PR #26 merged) - FEIGN-NOT-AN-EXPOSER-PROPOSE.md (PR #25 merged) Refresh active docs: - README.md "Deferred" section: trace_request_flow, find_route_callers, HTTP_CALLS/ASYNC_CALLS are shipped (not deferred). Add explicit pointers to the still-active TIER2-INCREMENTAL-REBUILD and REFRESH-CODE-INDEX-AUTO-MODE proposes for the incremental Kuzu work. - CODEBASE_REQUIREMENTS.md A.3: drop the stale 'ontology version 3' literal (now 9) and fix references to PLAN-CAPABILITIES-MODEL and CALL-GRAPH-PROPOSE to use their completed/ paths. Tense matches reality (call-graph layer is shipped, not deferred). - CODEBASE_REQUIREMENTS.md B.9: same fix for the propose/DEFERRED-CALL-GRAPH-PROPOSE.md reference; the propose lives under propose/completed/CALL-GRAPH-PROPOSE.md. No code changes. Test baseline unchanged: 290 passed, 4 skipped. * docs: add inline Java stubs for @CodebaseRoute / @CodebaseClient / @CodebaseProducer Per pushback on PR #34: the route, client, and producer brownfield annotations were mentioned 4x in README + CODEBASE_REQUIREMENTS but their @interface stubs were never shown inline. Users had to spelunk through tests/fixtures/ to know what to copy into their project. README §5 'Brownfield overrides — Last resort — source stubs' now has three explicit subsections: - 3a. Roles & capabilities — @CodebaseRole / @CodebaseCapability / @CodebaseCapabilities (class-level), with usage example. - 3b. Routes — @CodebaseRoute / @CodebaseRoutes + CodebaseRouteFrameworkKind / CodebaseRouteKind (method-level), with HTTP-endpoint and Kafka-consumer usage examples. - 3c. Clients & producers — @CodebaseClient / @CodebaseClients and @CodebaseProducer / @CodebaseProducers (method-level), with rest_template + kafka_send usage examples. Stub Java in the doc matches the verbatim sources under tests/fixtures/brownfield_route_stubs/ and brownfield_client_stubs/ (also referenced for copy-paste). Enum values mirror VALID_ROUTE_* and VALID_CLIENT_KINDS in java_ontology.py. CODEBASE_REQUIREMENTS.md A.2.1 updated to enumerate all three annotation families (roles, routes, clients/producers) and link to the matching README sections instead of only mentioning role stubs. No code change. Test baseline unchanged: 290 passed, 4 skipped.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Scope
Propose-only: rename role enum
FEIGN_CLIENT→CLIENTand addHTTP_CLIENTcapability. Implementation lands in PR-H1 after PR-F1 (#27 plans) and PR-G1 (#27 plans) ship.Also deletes
propose/DEFERRED-REST-CLIENT-MIGRATION-PROPOSE.md(2026-04-26) which reached the opposite conclusion. The architecture has moved on since then — capabilities exist, brownfield overrides exist,@CodebaseRoleexists — so its reasoning no longer applies.TL;DR
ast_java.py:90:"FeignClient": "FEIGN_CLIENT"→"FeignClient": "CLIENT""FeignClient": "HTTP_CLIENT"to_TYPE_ANN_TO_CAPABILITY(ast_java.py:111-114)MESSAGE_PRODUCERalready exists for KafkaTemplate/RabbitTemplate/JmsTemplate/StreamBridge/ApplicationEventPublisher — no async work in this propose@CodebaseRole(role="CLIENT")FEIGN_CLIENTis removed fromVALID_ROLESin the same PR; the existing validator rejects it with an error that lists the allowed roles.Why
Vocabulary cleanup driven by brownfield annotation honesty:
This mirrors the existing CONTROLLER (Spring-native role) + REST_CONTROLLER/MESSAGE_LISTENER (capability/peer) pattern.
Scope discipline
MESSAGE_PRODUCERalready covers itVALID_ROLEScheck)§9 [TBD]
5 items, all with v1 recommendations. Most important:
@CodebaseRole(role="CLIENT")without@CodebaseCapability("HTTP_CLIENT")— accept as-is (capabilities are independent; user may have gRPC client where HTTP_CLIENT would be wrong)_ROLE_SCORE_WEIGHTS["CLIENT"] = 0.06(same asFEIGN_CLIENTtoday)Sequencing
Companion docs
propose/FEIGN-NOT-AN-EXPOSER-PROPOSE.md(PR propose: @FeignClient is a caller, not an exposer #25, merged) — orthogonalpropose/CROSS-SERVICE-RESOLUTION-FLAG-PROPOSE.md(PR propose:cross_service_resolutionconfig flag (brownfield-first opt-in) #26, merged) — orthogonalplans/PLAN-FEIGN-NOT-AN-EXPOSER.md(PR plans: PR-F1 (Feign-not-an-exposer) + PR-G1 (cross_service_resolution flag) #27, open) — implements PR-F1plans/PLAN-CROSS-SERVICE-RESOLUTION-FLAG.md(PR plans: PR-F1 (Feign-not-an-exposer) + PR-G1 (cross_service_resolution flag) #27, open) — implements PR-G1Out of scope
MESSAGE_PRODUCERalready covers it)FEIGN_CLIENT(no users yet → hard rename is fine)