fix(java): no phantom JAX-RS routes for HTTP clients + JPA inline-annotation fields (#138)

Round-5 adversarial sweep (added /tmp/retrofit: interface/annotation/generics-
heavy). Two real Java bugs found and fixed; broad audit otherwise clean.

- JAX-RS false positives (HIGH): route detection fired on any file with @path +
  an HTTP-method annotation, so Retrofit — an HTTP CLIENT library whose
  @GET/@path come from retrofit2.http on interface methods — produced 28 phantom
  server routes. Require a javax/jakarta.ws.rs import (the defining signal for a
  real JAX-RS resource) before classifying as JAX-RS. Retrofit now yields 0
  routes; petclinic Spring routes (17) and genuine JAX-RS resources unaffected.

- JPA inline-annotated fields: `@Id private Long id;` (annotation inline with the
  declaration, the common javax.persistence style) was dropped — the parser
  treated the whole line as a pure annotation. Peel leading annotations and parse
  the remainder, so inline-annotated fields (incl. the @id primary key) are kept.

Regression tests added for both. Full suite green (3722 passing).

Note: the sweep also surfaced a Kotlin (.kt) call-graph receiver-loss self-edge —
out of this Java-scoped work; flagged for separate follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: clay-good

openspec/specs/analyzer/spec.md

@@ -5085,6 +5085,12 @@ The system SHALL inject call-graph edges into the file-level dependency graph fo
 
 > Decision recorded: 67580817
 > Date: 2026-06-17
+### Requirement: JaxrsRouteDetectionRequiresJavaxjakartawsrsImportToAvoidFalsePositivesFromHttpClientLibraries
+
+The system SHALL only classify a Java/Kotlin file as a JAX-RS server endpoint when it imports from the javax.ws.rs or jakarta.ws.rs package, to prevent false positives from HTTP client annotation libraries.
+
+> Decision recorded: f9de2e30
+> Date: 2026-06-17
 
 ## Technical Notes
 
@@ -5502,3 +5508,33 @@ The analyzer hardcoded JS/TS/Python extensions in several places, causing Java/K
 Java/Kotlin require imports only for cross-package references; same-package classes are used with no import. The dependency graph was built purely from import edges, so a Java project's file-level graph was nearly empty (spring-petclinic: 10 edges) while its call graph held 1261 — same-package relationships were invisible, hurting structural comprehension and leaving cluster views empty. Fix: (1) run injection for Java/Kotlin regardless of import-edge count, (2) seed the dedup set with existing edges so injected call edges never duplicate an import edge, (3) resolve call-graph file paths to absolute so the two id spaces align.
 
 **Consequences:** New exported SAME_PACKAGE_IMPLICIT_LANGS set (Java, Kotlin). injectCallGraphEdges now dedupes against pre-existing edges, making it safe to run alongside import edges. The absolute-path resolution also repairs the previously-silent no-op injection for Swift/C/C++. Java/Kotlin dependency graphs are now populated (petclinic 10→70 edges, gson 318→1517) with structural clusters; injected edges carry isCallEdge:true.
+
+### Require a ws.rs import for JAX-RS route detection
+
+**Status:** Approved
+**Date:** 2026-06-17
+**ID:** 954eac79
+
+JAX-RS route detection fired on any Java file containing both @Path and an HTTP-method annotation (@GET/@POST/...). Retrofit — an HTTP CLIENT library — uses identically-named @GET/@POST/@Path from retrofit2.http on interface methods (client request templates), so OpenLore hallucinated 28 phantom server routes for it (adversarial-audit finding). The defining signal for a real JAX-RS server resource is the javax.ws.rs / jakarta.ws.rs import, which Retrofit never has and Spring does not need. Gating JAX-RS detection on that import removes the false positives without affecting Spring (separate detection path) or genuine JAX-RS resources (which always import ws.rs).
+
+**Consequences:** extractJavaRouteDefinitions now requires an `import javax|jakarta.ws.rs` before classifying a file as JAX-RS. Retrofit/OkHttp client interfaces yield 0 routes; petclinic Spring routes (17) and JAX-RS resources (which import ws.rs) are unaffected.
+
+### JPA field parser handles inline annotations on the same line as the field declaration
+
+**Status:** Approved
+**Date:** 2026-06-17
+**ID:** 8605684f
+
+Common JPA patterns place annotations inline with the field (e.g. `@Id private Long id;`). The previous parser only recognized annotations on their own line, causing inline-annotated fields — including primary keys — to be silently dropped from schema extraction.
+
+**Consequences:** The parser now iteratively strips leading annotations before testing for a field match, correctly capturing inline-annotated fields. Pure-annotation lines still accumulate in pendingAnn for multi-line annotation stacks.
+
+### JAX-RS route detection requires javax/jakarta.ws.rs import to avoid false positives from HTTP client libraries
+
+**Status:** Approved
+**Date:** 2026-06-17
+**ID:** f9de2e30
+
+Retrofit interfaces use identically-named @GET/@POST/@Path annotations from retrofit2.http, which are client request templates, not server endpoints. Without checking the import package, the parser would emit phantom server routes for HTTP client definitions.
+
+**Consequences:** JAX-RS routes are only detected when the file imports from javax.ws.rs or jakarta.ws.rs; projects using non-standard JAX-RS re-exports would not be recognized. Retrofit and similar HTTP client interfaces are correctly excluded.

src/core/analyzer/http-route-parser.test.ts

@@ -1125,6 +1125,30 @@ public class UserResource {
     expect(paths).toContain('POST /users');
     expect(paths).toContain('GET /users/{id}');
   });
+
+  it('does NOT treat a Retrofit client interface as server routes (#138)', async () => {
+    // Retrofit's @GET/@Path come from retrofit2.http — client request templates,
+    // not server endpoints. Without the JAX-RS (ws.rs) import these must yield 0
+    // routes, otherwise OpenLore hallucinates a server API for a client library.
+    const file = await createFile(tempDir, 'GitHubService.java', `
+package com.example;
+
+import retrofit2.Call;
+import retrofit2.http.GET;
+import retrofit2.http.Path;
+
+public interface GitHubService {
+    @GET("/repos/{owner}/{repo}")
+    Call<Repo> getRepo(@Path("owner") String owner, @Path("repo") String repo);
+
+    @GET("/users/{user}/repos")
+    Call<List<Repo>> listRepos(@Path("user") String user);
+}
+`);
+
+    const routes = await extractJavaRouteDefinitions(file);
+    expect(routes).toEqual([]);
+  });
 });
 
 describe('extractAllHttpEdges with Java', () => {

src/core/analyzer/http-route-parser.ts

@@ -553,7 +553,14 @@ export async function extractJavaRouteDefinitions(filePath: string): Promise<Rou
   }
 
   const isSpring = /@(?:Rest)?Controller\b|@(?:Get|Post|Put|Delete|Patch)Mapping\b|@RequestMapping\b/.test(clean);
-  const isJaxrs = /@Path\b/.test(clean) && /@(?:GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/.test(clean);
+  // JAX-RS server annotations come from javax/jakarta.ws.rs. Require that import
+  // so we don't mistake an HTTP CLIENT library for a server: Retrofit interfaces
+  // use identically-named @GET/@POST/@Path from retrofit2.http (client request
+  // templates, not server endpoints) and would otherwise yield phantom routes.
+  const hasJaxrsImport = /\bimport\s+(?:static\s+)?(?:javax|jakarta)\.ws\.rs\b/.test(clean);
+  const isJaxrs = hasJaxrsImport
+    && /@Path\b/.test(clean)
+    && /@(?:GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/.test(clean);
 
   // ── Spring: shorthand mappings (@GetMapping, @PostMapping, …) ──────────────
   if (isSpring) {

src/core/analyzer/schema-extractor.test.ts

@@ -391,6 +391,32 @@ public class BaseEntity {
     expect(tables[0].fields[0].nullable).toBe(false);
   });
 
+  it('captures fields whose annotation is inline with the declaration (#138)', async () => {
+    // javax.persistence + inline annotations (`@Id private Long id;`) — the
+    // common style that a per-line "starts with @" check would drop.
+    const fp = await createFile(tmpDir, 'LegacyUser.java', `
+package com.example;
+
+import javax.persistence.Entity;
+import javax.persistence.Id;
+import javax.persistence.Column;
+
+@Entity
+public class LegacyUser {
+    @Id private Long id;
+    @Column(nullable = false) private String email;
+    private String nickname;
+}
+`);
+    const tables = await extractSchemas([fp], tmpDir);
+    expect(tables).toHaveLength(1);
+    const byName = Object.fromEntries(tables[0].fields.map(f => [f.name, f]));
+    expect(Object.keys(byName).sort()).toEqual(['email', 'id', 'nickname']);
+    expect(byName['id'].nullable).toBe(false);     // @Id ⇒ non-null
+    expect(byName['email'].nullable).toBe(false);  // nullable = false
+    expect(byName['nickname'].nullable).toBe(true);
+  });
+
   it('ignores Java files that are not entities', async () => {
     const fp = await createFile(tmpDir, 'PlainService.java', `
 package com.example;

src/core/analyzer/schema-extractor.ts

@@ -275,12 +275,21 @@ function parseJpaEntity(source: string, rel: string): SchemaTable[] {
 
     // Only inspect declarations directly inside the class body (depth 1), so
     // calls and locals inside method bodies (depth ≥ 2) are ignored.
-    if (depth === 1) {
-      if (trimmed.startsWith('@')) {
-        pendingAnn.push(trimmed);
-      } else if (trimmed) {
-        const fieldMatch = trimmed.match(JPA_FIELD_RE);
-        const isStatic = /\bstatic\b/.test(trimmed);
+    if (depth === 1 && trimmed) {
+      // Peel leading annotations into pendingAnn. They may be on their own line
+      // OR inline with the declaration (`@Id private Long id;`), so we strip them
+      // and then test whatever remains as a field — otherwise inline-annotated
+      // fields (very common, e.g. the @Id primary key) would be lost.
+      let rest = trimmed;
+      let am: RegExpMatchArray | null;
+      while ((am = rest.match(/^@[\w.]+(?:\([^)]*\))?\s*/))) {
+        pendingAnn.push(am[0].trim());
+        rest = rest.slice(am[0].length);
+      }
+
+      if (rest) {
+        const fieldMatch = rest.match(JPA_FIELD_RE);
+        const isStatic = /\bstatic\b/.test(rest);
         const isTransient = /@Transient\b/.test(pendingAnn.join(' '));
         if (fieldMatch && !isStatic && !isTransient) {
           const fieldName = fieldMatch[2];
@@ -295,6 +304,7 @@ function parseJpaEntity(source: string, rel: string): SchemaTable[] {
         }
         pendingAnn = [];
       }
+      // else: the line was pure annotation(s) — keep pendingAnn for the next line.
     }
 
     const opens = (lineText.match(/\{/g) ?? []).length;