gitnexus 1.6.6-rc.87 → 1.6.6-rc.89

package/dist/core/group/extractors/grpc-extractor.d.ts

@@ -2,6 +2,16 @@ import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js
 import type { ExtractedContract, RepoHandle } from '../types.js';
 export interface ProtoServiceInfo {
     package: string;
+    /**
+     * Optional. Value of `option java_package = "..."` declared in the
+     * same `.proto` file, when present and different from `package`.
+     * Empty string when the option is absent or equals `package`. Used by
+     * `detectionToContract()` to translate a Java import path back to the
+     * proto package whenever the proto explicitly publishes its generated
+     * Java code under a different namespace (a common pattern in
+     * Google-style protobuf projects).
+     */
+    javaPackage: string;
     serviceName: string;
     methods: string[];
     protoPath: string;
@@ -19,6 +29,57 @@ export declare class GrpcExtractor implements ContractExtractor {
      * either a service-level (`grpc::pkg.Svc/*`) or method-level
      * (`grpc::pkg.Svc/Method`) contract id, and selecting confidence
      * based on whether the proto map had an entry.
+     *
+     * Resolution order for the package prefix:
+     *
+     *   1. **Java-package translation** (when detection
+     *      supplied a `protoPackage` from a Java import).
+     *      A `.proto` in the SAME repo may set `option
+     *      java_package = "..."` to publish its generated
+     *      Java classes under a namespace different from
+     *      the proto `package`. Real-world projects (e.g.
+     *      Google Cloud Java APIs) routinely do this.
+     *      When the import-derived package matches that
+     *      `java_package` value, translate back to the
+     *      proto `package` so the resulting contract id
+     *      is wire-correct rather than Java-namespace.
+     *
+     *   2. **Per-repo proto map check** (when the same
+     *      service name has `.proto` candidates in this
+     *      repo). The proto file is the authoritative
+     *      source. If the proto's `package` agrees with
+     *      the import's `protoPackage`, both paths produce
+     *      the same FQN — emit it. If they DISAGREE (e.g.
+     *      a typo'd Java import, or a mismatched
+     *      java_package the reverse index didn't catch),
+     *      trust the proto map and warn — the import
+     *      MUST NOT silently overwrite an authoritative
+     *      proto package.
+     *
+     *   3. **Import-derived FQN fallback** (when neither
+     *      a `java_package` translation nor a proto map
+     *      candidate exists in this repo). Typical for the
+     *      "client-jar" pattern, where a consumer repo
+     *      depends on a published stub jar and never
+     *      carries the originating `.proto`. Use the
+     *      import path verbatim as the proto package. Note
+     *      the known limitation: when the published proto
+     *      sets `option java_package` differing from
+     *      `package`, the resulting FQN reflects the Java
+     *      namespace rather than the proto namespace and
+     *      will not match a provider repo's contract id —
+     *      we cannot translate without sight of the proto.
+     *
+     *   4. **Per-repo proto map (no import)** — the legacy
+     *      path. Used when the plugin didn't supply
+     *      `protoPackage` (no import statement, wildcard
+     *      import only, or non-Java languages that haven't
+     *      been retrofitted yet).
+     *
+     *   5. **Short-name fallback** — when none of the
+     *      above resolves a package, emit a service-only
+     *      short-name contract id (`grpc::Svc/*`),
+     *      preserving the pre-fix behaviour.
      */
     private detectionToContract;
     private dedupe;

package/dist/core/group/extractors/grpc-extractor.js

@@ -170,6 +170,18 @@ function extractProtoImports(content) {
     }
     return imports;
 }
+/**
+ * Extract `option java_package = "..."` from a `.proto` file, if any.
+ * The Java code generator places generated `XxxGrpc.java` classes under
+ * this package (instead of the proto `package` declaration) when the
+ * option is set. Real-world projects (Google Cloud Java APIs, internal
+ * shaded SDKs) routinely use this to publish their Java artifacts under
+ * a corporate namespace different from the wire-protocol package.
+ */
+function extractJavaPackageOption(content) {
+    const m = content.match(/^\s*option\s+java_package\s*=\s*"([\w.]+)"\s*;/m);
+    return m?.[1] ?? '';
+}
 function longestSharedSegmentRun(aPath, bPath) {
     const a = aPath.split('/').filter(Boolean);
     const b = bPath.split('/').filter(Boolean);
@@ -188,6 +200,7 @@ function longestSharedSegmentRun(aPath, bPath) {
 }
 async function buildProtoContext(repoPath) {
     const servicesByName = new Map();
+    const servicesByJavaPackage = new Map();
     // `.gitnexusignore` / `.gitignore` honoured via the shared IgnoreService —
     // see `filesystem-walker.ts` for the canonical pattern. Replaces a
     // hardcoded `[node_modules, .git, vendor]` array; those names plus the
@@ -246,6 +259,13 @@ async function buildProtoContext(repoPath) {
         if (!content)
             continue;
         const pkg = resolvePackage(normalizedRel);
+        const javaPkgOption = extractJavaPackageOption(content);
+        // Only retain `javaPackage` when it actively diverges from `pkg`.
+        // When equal (or absent), the import-derived path produces the
+        // same FQN as the proto-derived path, so no translation is needed
+        // and we keep the field empty to avoid populating the reverse
+        // index with redundant entries.
+        const javaPackage = javaPkgOption && javaPkgOption !== pkg ? javaPkgOption : '';
         const serviceBlocks = extractServiceBlocks(content);
         for (const block of serviceBlocks) {
             const rpcRe = /rpc\s+(\w+)\s*\(/g;
@@ -256,6 +276,7 @@ async function buildProtoContext(repoPath) {
             }
             const info = {
                 package: pkg,
+                javaPackage,
                 serviceName: block.name,
                 methods,
                 protoPath: normalizedRel,
@@ -263,9 +284,14 @@ async function buildProtoContext(repoPath) {
             const existing = servicesByName.get(block.name) ?? [];
             existing.push(info);
             servicesByName.set(block.name, existing);
+            if (javaPackage) {
+                const byJava = servicesByJavaPackage.get(javaPackage) ?? [];
+                byJava.push(info);
+                servicesByJavaPackage.set(javaPackage, byJava);
+            }
         }
     }
-    return { packagesByProto, servicesByName };
+    return { packagesByProto, servicesByName, servicesByJavaPackage };
 }
 export async function buildProtoMap(repoPath) {
     const { servicesByName } = await buildProtoContext(repoPath);
@@ -311,6 +337,7 @@ export class GrpcExtractor {
         const out = [];
         const protoContext = await buildProtoContext(repoPath);
         const protoMap = protoContext.servicesByName;
+        const javaPackageMap = protoContext.servicesByJavaPackage;
         // ─── Proto files — definitive provider source ─────────────────
         // When tree-sitter-proto is available, .proto files are handled by
         // the plugin loop below (they're in GRPC_SCAN_GLOB). Otherwise
@@ -360,7 +387,7 @@ export class GrpcExtractor {
                 continue;
             }
             for (const d of detections) {
-                const contract = this.detectionToContract(d, rel, protoMap);
+                const contract = this.detectionToContract(d, rel, protoMap, javaPackageMap);
                 if (contract)
                     out.push(contract);
             }
@@ -373,8 +400,157 @@ export class GrpcExtractor {
      * either a service-level (`grpc::pkg.Svc/*`) or method-level
      * (`grpc::pkg.Svc/Method`) contract id, and selecting confidence
      * based on whether the proto map had an entry.
+     *
+     * Resolution order for the package prefix:
+     *
+     *   1. **Java-package translation** (when detection
+     *      supplied a `protoPackage` from a Java import).
+     *      A `.proto` in the SAME repo may set `option
+     *      java_package = "..."` to publish its generated
+     *      Java classes under a namespace different from
+     *      the proto `package`. Real-world projects (e.g.
+     *      Google Cloud Java APIs) routinely do this.
+     *      When the import-derived package matches that
+     *      `java_package` value, translate back to the
+     *      proto `package` so the resulting contract id
+     *      is wire-correct rather than Java-namespace.
+     *
+     *   2. **Per-repo proto map check** (when the same
+     *      service name has `.proto` candidates in this
+     *      repo). The proto file is the authoritative
+     *      source. If the proto's `package` agrees with
+     *      the import's `protoPackage`, both paths produce
+     *      the same FQN — emit it. If they DISAGREE (e.g.
+     *      a typo'd Java import, or a mismatched
+     *      java_package the reverse index didn't catch),
+     *      trust the proto map and warn — the import
+     *      MUST NOT silently overwrite an authoritative
+     *      proto package.
+     *
+     *   3. **Import-derived FQN fallback** (when neither
+     *      a `java_package` translation nor a proto map
+     *      candidate exists in this repo). Typical for the
+     *      "client-jar" pattern, where a consumer repo
+     *      depends on a published stub jar and never
+     *      carries the originating `.proto`. Use the
+     *      import path verbatim as the proto package. Note
+     *      the known limitation: when the published proto
+     *      sets `option java_package` differing from
+     *      `package`, the resulting FQN reflects the Java
+     *      namespace rather than the proto namespace and
+     *      will not match a provider repo's contract id —
+     *      we cannot translate without sight of the proto.
+     *
+     *   4. **Per-repo proto map (no import)** — the legacy
+     *      path. Used when the plugin didn't supply
+     *      `protoPackage` (no import statement, wildcard
+     *      import only, or non-Java languages that haven't
+     *      been retrofitted yet).
+     *
+     *   5. **Short-name fallback** — when none of the
+     *      above resolves a package, emit a service-only
+     *      short-name contract id (`grpc::Svc/*`),
+     *      preserving the pre-fix behaviour.
      */
-    detectionToContract(d, filePath, protoMap) {
+    detectionToContract(d, filePath, protoMap, javaPackageMap) {
+        if (d.protoPackage) {
+            // Step 1: java_package translation. The import-derived package
+            // may be the `option java_package` value of a `.proto` in the
+            // SAME repo. Look it up and, if found for the same service name,
+            // use the underlying proto `package` to build a wire-correct
+            // contract id.
+            const javaCandidates = javaPackageMap.get(d.protoPackage) ?? [];
+            const javaTranslated = javaCandidates.find((p) => p.serviceName === d.serviceName);
+            if (javaTranslated) {
+                const cid = d.methodName
+                    ? contractId(javaTranslated.package, d.serviceName, d.methodName)
+                    : serviceContractId(javaTranslated.package, d.serviceName);
+                const meta = {
+                    service: d.serviceName,
+                    source: d.source,
+                    package: javaTranslated.package,
+                    protoPackageSource: 'import-translated',
+                };
+                if (d.methodName)
+                    meta.method = d.methodName;
+                return makeContract(cid, d.role, filePath, d.symbolName, d.confidenceWithProto, meta);
+            }
+            // Step 2: proto map cross-check. When this repo also carries a
+            // `.proto` defining the same short service name, the proto is
+            // authoritative and decides the package. The import is only used
+            // to disambiguate among same-short-name candidates when the
+            // resolution heuristic can't pick a unique winner on path alone.
+            const candidates = protoMap.get(d.serviceName) ?? [];
+            if (candidates.length > 0) {
+                const proto = resolveProtoConflict(d.serviceName, filePath, candidates);
+                if (proto === null) {
+                    // Ambiguous proto resolution; resolveProtoConflict already warned.
+                    return null;
+                }
+                const protoPkg = proto.package;
+                if (protoPkg === d.protoPackage) {
+                    // Both paths agree.
+                    const cid = d.methodName
+                        ? contractId(protoPkg, d.serviceName, d.methodName)
+                        : serviceContractId(protoPkg, d.serviceName);
+                    const meta = {
+                        service: d.serviceName,
+                        source: d.source,
+                        package: protoPkg,
+                        protoPackageSource: 'import',
+                    };
+                    if (d.methodName)
+                        meta.method = d.methodName;
+                    return makeContract(cid, d.role, filePath, d.symbolName, d.confidenceWithProto, meta);
+                }
+                // Disagreement. Trust the proto file and emit a warning so
+                // operators can investigate the import. This protects against
+                // the symmetric Finding 2 case: a stale or typo'd Java import
+                // silently corrupting the contract id of a service whose
+                // `.proto` lives in the same repo.
+                logger.warn(`[grpc-extractor] Java import package "${d.protoPackage}" for service ` +
+                    `"${d.serviceName}" disagrees with local proto package "${protoPkg}" at ` +
+                    `${filePath}; using proto package as authoritative source`);
+                const cid = d.methodName
+                    ? contractId(protoPkg, d.serviceName, d.methodName)
+                    : serviceContractId(protoPkg, d.serviceName);
+                const meta = {
+                    service: d.serviceName,
+                    source: d.source,
+                    package: protoPkg,
+                    protoPackageSource: 'proto-override',
+                    importPackage: d.protoPackage,
+                };
+                if (d.methodName)
+                    meta.method = d.methodName;
+                return makeContract(cid, d.role, filePath, d.symbolName, d.confidenceWithProto, meta);
+            }
+            // Step 3: import-derived fallback. No `.proto` in this repo
+            // names the service, and no `java_package` reverse-lookup
+            // matched. Emit the FQN with the import-derived package. This
+            // is the typical client-jar consumer path.
+            //
+            // Known limitation: when the published proto sets
+            // `option java_package` to a value that differs from
+            // `package`, this path produces a contract id that reflects
+            // the Java namespace, not the proto namespace, and will not
+            // match a provider repo. Resolving that case requires
+            // group-level proto knowledge, which is intentionally out of
+            // scope for this fix.
+            const cid = d.methodName
+                ? contractId(d.protoPackage, d.serviceName, d.methodName)
+                : serviceContractId(d.protoPackage, d.serviceName);
+            const meta = {
+                service: d.serviceName,
+                source: d.source,
+                package: d.protoPackage,
+                protoPackageSource: 'import',
+            };
+            if (d.methodName)
+                meta.method = d.methodName;
+            return makeContract(cid, d.role, filePath, d.symbolName, d.confidenceWithProto, meta);
+        }
+        // Steps 4 + 5: legacy per-repo proto map resolution (no import).
         const candidates = protoMap.get(d.serviceName) ?? [];
         const proto = resolveProtoConflict(d.serviceName, filePath, candidates);
         // If there were proto candidates but resolution was ambiguous, skip

package/dist/core/group/extractors/grpc-patterns/java.js

@@ -66,6 +66,32 @@ const STUB_PATTERNS = compilePatterns({
         },
     ],
 });
+// `import <pkg>.<XxxGrpc>;` — captures the proto package of the
+// imported gRPC class (e.g. `cn.unipus.ucf.admin.proto.client.service`
+// for `import cn.unipus.ucf.admin.proto.client.service.ContentRpcServiceGrpc`).
+// Used by `scan` to build a per-file `XxxGrpc → fullPackage` map so
+// consumer-side detections can carry a fully-qualified contract id
+// even when the consumer repo does not contain any `.proto` files.
+//
+// `import static …` is excluded by tree-sitter shape: the `name:`
+// field is only present on the non-static form. `import w.x.*;` is
+// also excluded for the same reason — wildcard imports have an
+// `asterisk` child instead of a named identifier.
+const GRPC_CLASS_IMPORT_PATTERNS = compilePatterns({
+    name: 'java-grpc-class-import',
+    language: Java,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (import_declaration
+          (scoped_identifier
+            scope: (_) @import_pkg
+            name: (identifier) @import_name (#match? @import_name "Grpc$")))
+      `,
+        },
+    ],
+});
 /**
  * Check whether a `class_declaration` node has a `@GrpcService`
  * annotation in its modifiers list. In tree-sitter-java, class-level
@@ -108,6 +134,37 @@ export const JAVA_GRPC_PLUGIN = {
     scan(tree) {
         const out = [];
         const emittedClassIds = new Set();
+        // ─── Build per-file gRPC class import map ───────────────────────
+        // Maps `XxxGrpc` (short class name) → fully-qualified proto package
+        // (e.g. `cn.unipus.ucf.admin.proto.client.service`). Used below to
+        // tag both provider and consumer detections with a `protoPackage`
+        // so the orchestrator can build a fully-qualified contract id
+        // without depending on the current repo carrying any `.proto`
+        // files. This is the key fix for client-jar consumer repos.
+        //
+        // Same-short-name disambiguation: when two distinct `import` lines
+        // bring different `XxxGrpc` classes from different packages into
+        // the same file (rare for grpc — the second import would be a
+        // compile error in Java), the last one wins. Java's compiler
+        // forbids that case so we don't bother modelling it.
+        const grpcClassImports = new Map();
+        for (const match of runCompiledPatterns(GRPC_CLASS_IMPORT_PATTERNS, tree)) {
+            const pkgNode = match.captures.import_pkg;
+            const nameNode = match.captures.import_name;
+            if (!pkgNode || !nameNode)
+                continue;
+            grpcClassImports.set(nameNode.text, pkgNode.text);
+        }
+        /**
+         * Resolve the fully-qualified proto package for a short service
+         * name in this file. Looks up `<serviceName>Grpc` in the import
+         * map; returns `undefined` when the class is referenced via a
+         * fully-qualified name on every call site (no import line) or
+         * when only a wildcard import is present. The orchestrator falls
+         * back to the per-repo proto map in that case, preserving the
+         * pre-fix behaviour.
+         */
+        const protoPackageFor = (serviceName) => grpcClassImports.get(`${serviceName}Grpc`);
         // ─── Providers: scoped form (`...Grpc.XxxImplBase`) ─────────────
         for (const match of runCompiledPatterns(SCOPED_IMPL_BASE_PATTERNS, tree)) {
             const classNode = match.captures.class;
@@ -119,6 +176,7 @@ export const JAVA_GRPC_PLUGIN = {
                 continue;
             emittedClassIds.add(classNode.id);
             const annotated = hasGrpcServiceAnnotation(classNode);
+            const protoPackage = protoPackageFor(serviceName);
             out.push({
                 role: 'provider',
                 serviceName,
@@ -126,6 +184,7 @@ export const JAVA_GRPC_PLUGIN = {
                 source: annotated ? 'java_grpc_service' : 'java_impl_base',
                 confidenceWithProto: 0.8,
                 confidenceWithoutProto: 0.65,
+                ...(protoPackage ? { protoPackage } : {}),
             });
         }
         // ─── Providers: plain form (`XxxImplBase`) ──────────────────────
@@ -141,6 +200,7 @@ export const JAVA_GRPC_PLUGIN = {
                 continue;
             emittedClassIds.add(classNode.id);
             const annotated = hasGrpcServiceAnnotation(classNode);
+            const protoPackage = protoPackageFor(serviceName);
             out.push({
                 role: 'provider',
                 serviceName,
@@ -148,6 +208,7 @@ export const JAVA_GRPC_PLUGIN = {
                 source: annotated ? 'java_grpc_service' : 'java_impl_base',
                 confidenceWithProto: 0.8,
                 confidenceWithoutProto: 0.65,
+                ...(protoPackage ? { protoPackage } : {}),
             });
         }
         // ─── Consumers: `XxxGrpc.newBlockingStub(...)` / `newStub(...)` ─
@@ -159,6 +220,7 @@ export const JAVA_GRPC_PLUGIN = {
             if (!grpcMatch)
                 continue;
             const serviceName = grpcMatch[1];
+            const protoPackage = protoPackageFor(serviceName);
             out.push({
                 role: 'consumer',
                 serviceName,
@@ -166,6 +228,7 @@ export const JAVA_GRPC_PLUGIN = {
                 source: 'java_stub',
                 confidenceWithProto: 0.75,
                 confidenceWithoutProto: 0.55,
+                ...(protoPackage ? { protoPackage } : {}),
             });
         }
         return out;

package/dist/core/group/extractors/grpc-patterns/types.d.ts

@@ -33,6 +33,18 @@ export interface GrpcDetection {
     confidenceWithProto: number;
     /** Confidence when the proto map has no entry. */
     confidenceWithoutProto: number;
+    /**
+     * Optional. Fully-qualified proto package the detection's service
+     * belongs to (e.g. `cn.unipus.ucf.admin.proto.client.service`),
+     * derived directly from the source file's import statements when
+     * available. When set, the orchestrator uses this package to build
+     * the contract id INSTEAD of consulting the per-repo proto map —
+     * letting consumer repos that don't carry `.proto` files (the
+     * client-jar architecture used by most Java gRPC microservices)
+     * still emit a fully-qualified contract id that matches the
+     * provider repo's contract id verbatim.
+     */
+    protoPackage?: string;
 }
 /**
  * One language-scoped gRPC plugin. Plugins own the tree-sitter grammar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.87",
+  "version": "1.6.6-rc.89",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",