gitnexus 1.6.0 → 1.6.1

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

@@ -0,0 +1,46 @@
+import * as path from 'node:path';
+import { GO_GRPC_PLUGIN } from './go.js';
+import { JAVA_GRPC_PLUGIN } from './java.js';
+import { PYTHON_GRPC_PLUGIN } from './python.js';
+import { JAVASCRIPT_GRPC_PLUGIN, TYPESCRIPT_GRPC_PLUGIN, TSX_GRPC_PLUGIN } from './node.js';
+import { PROTO_GRPC_PLUGIN } from './proto.js';
+export { PROTO_GRPC_PLUGIN, extractPackageFromTree } from './proto.js';
+/**
+ * File-extension → gRPC language plugin registry. Mirrors the shape
+ * of `http-patterns/index.ts` and `topic-patterns/index.ts`.
+ *
+ * `.proto` files are registered only when `tree-sitter-proto` is
+ * available (it's an optionalDependency). When absent, the orchestrator
+ * falls back to the built-in manual proto parser.
+ */
+const REGISTRY = {
+    '.go': GO_GRPC_PLUGIN,
+    '.java': JAVA_GRPC_PLUGIN,
+    '.py': PYTHON_GRPC_PLUGIN,
+    '.js': JAVASCRIPT_GRPC_PLUGIN,
+    '.jsx': JAVASCRIPT_GRPC_PLUGIN,
+    '.ts': TYPESCRIPT_GRPC_PLUGIN,
+    '.tsx': TSX_GRPC_PLUGIN,
+    ...(PROTO_GRPC_PLUGIN ? { '.proto': PROTO_GRPC_PLUGIN } : {}),
+};
+/**
+ * Glob for source files worth scanning for gRPC server/client patterns.
+ * Includes `.proto` when the grammar is available.
+ */
+export const GRPC_SCAN_GLOB = PROTO_GRPC_PLUGIN
+    ? '**/*.{go,java,py,ts,tsx,js,jsx,proto}'
+    : '**/*.{go,java,py,ts,tsx,js,jsx}';
+/**
+ * Whether the tree-sitter proto plugin is available. The orchestrator
+ * uses this to decide between the tree-sitter path and the fallback
+ * manual parser for `.proto` files.
+ */
+export const hasProtoPlugin = PROTO_GRPC_PLUGIN !== null;
+/**
+ * Return the gRPC plugin registered for the given file's extension,
+ * or `undefined` if the extension is not registered.
+ */
+export function getPluginForFile(rel) {
+    const ext = path.extname(rel).toLowerCase();
+    return REGISTRY[ext];
+}

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

@@ -0,0 +1,2 @@
+import type { GrpcLanguagePlugin } from './types.js';
+export declare const JAVA_GRPC_PLUGIN: GrpcLanguagePlugin;

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

@@ -0,0 +1,173 @@
+import Java from 'tree-sitter-java';
+import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js';
+/**
+ * Java gRPC plugin. Detects:
+ *   - Provider: classes extending `XxxServiceGrpc.XxxServiceImplBase`
+ *     (with or without a `@GrpcService` annotation; the annotation
+ *     only affects confidence labelling in the original regex version
+ *     — here we emit a single detection per class and pick the source
+ *     label based on whether the annotation is present).
+ *   - Consumer: `XxxServiceGrpc.newBlockingStub(ch)` /
+ *     `XxxServiceGrpc.newStub(ch)` calls.
+ */
+const IMPL_BASE_RE = /^(\w+)ImplBase$/;
+const GRPC_SUFFIX_RE = /^(\w+)Grpc$/;
+// Classes extending `ScopedType.ScopedType` where the inner name ends
+// in ImplBase. Covers `XxxServiceGrpc.XxxServiceImplBase`.
+// Note: tree-sitter-java's `scoped_type_identifier` exposes its two
+// segments as positional `type_identifier` children, NOT as named
+// `scope:`/`name:` fields. We match positionally here and rely on the
+// grammar's left-to-right ordering: first child = outer, second = inner.
+const SCOPED_IMPL_BASE_PATTERNS = compilePatterns({
+    name: 'java-grpc-scoped-impl-base',
+    language: Java,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (class_declaration
+          name: (identifier) @class_name
+          superclass: (superclass
+            (scoped_type_identifier
+              (type_identifier) @outer
+              (type_identifier) @inner (#match? @inner "ImplBase$")))) @class
+      `,
+        },
+    ],
+});
+// Classes extending a simple `XxxImplBase` identifier (no scope).
+const PLAIN_IMPL_BASE_PATTERNS = compilePatterns({
+    name: 'java-grpc-plain-impl-base',
+    language: Java,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (class_declaration
+          name: (identifier) @class_name
+          superclass: (superclass
+            (type_identifier) @plain_type (#match? @plain_type "ImplBase$"))) @class
+      `,
+        },
+    ],
+});
+// gRPC stub factories: `XxxGrpc.newStub(ch)` / `XxxGrpc.newBlockingStub(ch)`.
+const STUB_PATTERNS = compilePatterns({
+    name: 'java-grpc-stub',
+    language: Java,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (method_invocation
+          object: (identifier) @grpc_cls
+          name: (identifier) @method (#match? @method "^new(Blocking)?Stub$"))
+      `,
+        },
+    ],
+});
+/**
+ * Check whether a `class_declaration` node has a `@GrpcService`
+ * annotation in its modifiers list. In tree-sitter-java, class-level
+ * annotations live under `(class_declaration (modifiers (marker_annotation|annotation)))`.
+ */
+function hasGrpcServiceAnnotation(classNode) {
+    for (let i = 0; i < classNode.namedChildCount; i++) {
+        const child = classNode.namedChild(i);
+        if (!child || child.type !== 'modifiers')
+            continue;
+        for (let j = 0; j < child.namedChildCount; j++) {
+            const mod = child.namedChild(j);
+            if (!mod)
+                continue;
+            if (mod.type !== 'marker_annotation' && mod.type !== 'annotation')
+                continue;
+            const nameNode = mod.childForFieldName('name');
+            if (nameNode?.text === 'GrpcService')
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Given the inner type_identifier text like `AuthServiceImplBase`,
+ * return the service name (`AuthService`), or null if the text
+ * doesn't end in `ImplBase`.
+ */
+function extractServiceFromImplBase(text) {
+    const m = IMPL_BASE_RE.exec(text);
+    if (!m)
+        return null;
+    // Strip a trailing `Grpc` on the service name too — the original
+    // regex replaces `Grpc$` on the extracted prefix.
+    return m[1].replace(/Grpc$/, '');
+}
+export const JAVA_GRPC_PLUGIN = {
+    name: 'java-grpc',
+    language: Java,
+    scan(tree) {
+        const out = [];
+        const emittedClassIds = new Set();
+        // ─── Providers: scoped form (`...Grpc.XxxImplBase`) ─────────────
+        for (const match of runCompiledPatterns(SCOPED_IMPL_BASE_PATTERNS, tree)) {
+            const classNode = match.captures.class;
+            const innerNode = match.captures.inner;
+            if (!classNode || !innerNode)
+                continue;
+            const serviceName = extractServiceFromImplBase(innerNode.text);
+            if (!serviceName)
+                continue;
+            emittedClassIds.add(classNode.id);
+            const annotated = hasGrpcServiceAnnotation(classNode);
+            out.push({
+                role: 'provider',
+                serviceName,
+                symbolName: serviceName,
+                source: annotated ? 'java_grpc_service' : 'java_impl_base',
+                confidenceWithProto: 0.8,
+                confidenceWithoutProto: 0.65,
+            });
+        }
+        // ─── Providers: plain form (`XxxImplBase`) ──────────────────────
+        for (const match of runCompiledPatterns(PLAIN_IMPL_BASE_PATTERNS, tree)) {
+            const classNode = match.captures.class;
+            const plainNode = match.captures.plain_type;
+            if (!classNode || !plainNode)
+                continue;
+            if (emittedClassIds.has(classNode.id))
+                continue;
+            const serviceName = extractServiceFromImplBase(plainNode.text);
+            if (!serviceName)
+                continue;
+            emittedClassIds.add(classNode.id);
+            const annotated = hasGrpcServiceAnnotation(classNode);
+            out.push({
+                role: 'provider',
+                serviceName,
+                symbolName: serviceName,
+                source: annotated ? 'java_grpc_service' : 'java_impl_base',
+                confidenceWithProto: 0.8,
+                confidenceWithoutProto: 0.65,
+            });
+        }
+        // ─── Consumers: `XxxGrpc.newBlockingStub(...)` / `newStub(...)` ─
+        for (const match of runCompiledPatterns(STUB_PATTERNS, tree)) {
+            const grpcClsNode = match.captures.grpc_cls;
+            if (!grpcClsNode)
+                continue;
+            const grpcMatch = GRPC_SUFFIX_RE.exec(grpcClsNode.text);
+            if (!grpcMatch)
+                continue;
+            const serviceName = grpcMatch[1];
+            out.push({
+                role: 'consumer',
+                serviceName,
+                symbolName: `${serviceName}Stub`,
+                source: 'java_stub',
+                confidenceWithProto: 0.75,
+                confidenceWithoutProto: 0.55,
+            });
+        }
+        return out;
+    },
+};

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

@@ -0,0 +1,4 @@
+import type { GrpcLanguagePlugin } from './types.js';
+export declare const JAVASCRIPT_GRPC_PLUGIN: GrpcLanguagePlugin;
+export declare const TYPESCRIPT_GRPC_PLUGIN: GrpcLanguagePlugin;
+export declare const TSX_GRPC_PLUGIN: GrpcLanguagePlugin;

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

@@ -0,0 +1,290 @@
+import JavaScript from 'tree-sitter-javascript';
+import TypeScript from 'tree-sitter-typescript';
+import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
+/**
+ * Node.js / TypeScript gRPC plugin family. Detects:
+ *   - Provider: NestJS `@GrpcMethod('Service', 'Method')` decorators
+ *   - Consumer: NestJS `@GrpcClient(...) readonly x!: XxxServiceClient`
+ *   - Consumer: `client.getService<X>('AuthService')`
+ *   - Consumer: `new XxxServiceClient(...)` (generated client constructor)
+ *   - Consumer: `new foo.bar.Xxx(...)` when the file uses
+ *     `loadPackageDefinition` (gRPC dynamic proto loader)
+ *
+ * As with the HTTP `node.ts`, pattern sources are defined once and
+ * compiled against three grammar variants (JS / TS / TSX) because
+ * `Parser.Query` is not portable across grammar objects.
+ */
+const SERVICE_CLIENT_RE = /^(\w+Service)Client$/;
+const CAPITALIZED_SERVICE_RE = /^[A-Z]\w+$/;
+// @GrpcMethod('Service', 'Method')
+const GRPC_METHOD_SPEC = {
+    meta: {},
+    query: `
+    (decorator
+      (call_expression
+        function: (identifier) @dec (#eq? @dec "GrpcMethod")
+        arguments: (arguments
+          . [(string) (template_string)] @service
+          . [(string) (template_string)] @method)))
+  `,
+};
+// @GrpcClient(...) standalone decorator — the plugin walks to the next
+// sibling (a field definition) to read its type annotation.
+const GRPC_CLIENT_SPEC = {
+    meta: {},
+    query: `
+    (decorator
+      (call_expression
+        function: (identifier) @dec (#eq? @dec "GrpcClient"))) @grpc_client_decorator
+  `,
+};
+// `.getService<X>('AuthService')` / `.getService('AuthService')`
+const GET_SERVICE_SPEC = {
+    meta: {},
+    query: `
+    (call_expression
+      function: (member_expression
+        property: (property_identifier) @method (#eq? @method "getService"))
+      arguments: (arguments . [(string) (template_string)] @service))
+  `,
+};
+// `new XxxServiceClient(...)` — bare identifier constructor.
+const NEW_SIMPLE_CTOR_SPEC = {
+    meta: {},
+    query: `
+    (new_expression
+      constructor: (identifier) @ctor)
+  `,
+};
+// `new foo.bar.XxxService(...)` — qualified constructor.
+const NEW_QUALIFIED_CTOR_SPEC = {
+    meta: {},
+    query: `
+    (new_expression
+      constructor: (member_expression
+        property: (property_identifier) @ctor))
+  `,
+};
+// Detect whether the file uses `loadPackageDefinition` (gRPC dynamic
+// proto loader). Matches either a bare call or an `obj.loadPackageDefinition(...)`
+// call. Plugin gates the qualified-constructor consumer on this —
+// structural check avoids materializing `tree.rootNode.text` for every file.
+const LOAD_PACKAGE_DEFINITION_SPEC = {
+    meta: {},
+    query: `
+    (call_expression
+      function: [
+        (identifier) @fn (#eq? @fn "loadPackageDefinition")
+        (member_expression property: (property_identifier) @fn (#eq? @fn "loadPackageDefinition"))
+      ])
+  `,
+};
+function compileBundle(language, name) {
+    const mk = (spec, suffix) => compilePatterns({
+        name: `${name}-${suffix}`,
+        language,
+        patterns: [spec],
+    });
+    return {
+        grpcMethod: mk(GRPC_METHOD_SPEC, 'grpc-method'),
+        grpcClient: mk(GRPC_CLIENT_SPEC, 'grpc-client'),
+        getService: mk(GET_SERVICE_SPEC, 'get-service'),
+        newSimpleCtor: mk(NEW_SIMPLE_CTOR_SPEC, 'new-simple-ctor'),
+        newQualifiedCtor: mk(NEW_QUALIFIED_CTOR_SPEC, 'new-qualified-ctor'),
+        loadPackageDefinition: mk(LOAD_PACKAGE_DEFINITION_SPEC, 'load-package-definition'),
+    };
+}
+const JAVASCRIPT_BUNDLE = compileBundle(JavaScript, 'javascript-grpc');
+const TYPESCRIPT_BUNDLE = compileBundle(TypeScript.typescript, 'typescript-grpc');
+const TSX_BUNDLE = compileBundle(TypeScript.tsx, 'tsx-grpc');
+/**
+ * Given a `@GrpcClient(...)` decorator node, find the type annotation
+ * text of the field it decorates (e.g. `AuthServiceClient`).
+ *
+ * In tree-sitter-typescript, decorators on class fields can appear in
+ * two configurations:
+ *   - As a CHILD of `public_field_definition` alongside the field's
+ *     type annotation (the common case for NestJS `@GrpcClient`).
+ *   - As a SIBLING of the field in `class_body` (for method
+ *     decorators, but kept for resilience against grammar variants).
+ * We walk the parent container and search for a type annotation.
+ */
+function resolveGrpcClientFieldType(decoratorNode) {
+    const parent = decoratorNode.parent;
+    if (!parent)
+        return null;
+    // Case 1: decorator is a child of the field definition — search
+    // the parent itself (which is the field definition) for a
+    // type_annotation child.
+    if (parent.type === 'public_field_definition' || parent.type.endsWith('field_definition')) {
+        return findFirstTypeAnnotationText(parent);
+    }
+    // Case 2: decorator is a sibling of the field in a class_body — walk
+    // forward through subsequent siblings until we find a node containing
+    // a type annotation.
+    for (let i = 0; i < parent.namedChildCount; i++) {
+        const child = parent.namedChild(i);
+        if (child && child.id === decoratorNode.id) {
+            for (let j = i + 1; j < parent.namedChildCount; j++) {
+                const next = parent.namedChild(j);
+                if (!next)
+                    continue;
+                if (next.type === 'decorator')
+                    continue;
+                const typeText = findFirstTypeAnnotationText(next);
+                if (typeText)
+                    return typeText;
+                return null;
+            }
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Recursively search `node` for the first `type_annotation` child and
+ * return the text of its inner `type_identifier`, or null. Handles
+ * both `public_field_definition` and its variants.
+ */
+function findFirstTypeAnnotationText(node) {
+    if (node.type === 'type_annotation') {
+        for (let i = 0; i < node.namedChildCount; i++) {
+            const child = node.namedChild(i);
+            if (!child)
+                continue;
+            if (child.type === 'type_identifier')
+                return child.text;
+        }
+        return null;
+    }
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child)
+            continue;
+        const found = findFirstTypeAnnotationText(child);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function scanBundle(bundle, tree) {
+    const out = [];
+    // ─── Provider: @GrpcMethod('Service', 'Method') ──────────────────
+    for (const match of runCompiledPatterns(bundle.grpcMethod, tree)) {
+        const svcNode = match.captures.service;
+        const methodNode = match.captures.method;
+        if (!svcNode || !methodNode)
+            continue;
+        const svc = unquoteLiteral(svcNode.text);
+        const mth = unquoteLiteral(methodNode.text);
+        if (!svc || !mth)
+            continue;
+        out.push({
+            role: 'provider',
+            serviceName: svc,
+            symbolName: `${svc}.${mth}`,
+            source: 'ts_grpc_method',
+            methodName: mth,
+            // @GrpcMethod hard-coded confidence 0.8 in the original code
+            // regardless of whether the proto map has a match.
+            confidenceWithProto: 0.8,
+            confidenceWithoutProto: 0.8,
+        });
+    }
+    // ─── Consumer: @GrpcClient() field with XxxServiceClient type ────
+    for (const match of runCompiledPatterns(bundle.grpcClient, tree)) {
+        const decoratorNode = match.captures.grpc_client_decorator;
+        if (!decoratorNode)
+            continue;
+        const typeText = resolveGrpcClientFieldType(decoratorNode);
+        if (!typeText)
+            continue;
+        const svcMatch = SERVICE_CLIENT_RE.exec(typeText);
+        if (!svcMatch)
+            continue;
+        const serviceName = svcMatch[1];
+        out.push({
+            role: 'consumer',
+            serviceName,
+            symbolName: `${serviceName}Client`,
+            source: 'ts_grpc_client_decorator',
+            confidenceWithProto: 0.75,
+            confidenceWithoutProto: 0.55,
+        });
+    }
+    // ─── Consumer: client.getService<X>('Service') ───────────────────
+    for (const match of runCompiledPatterns(bundle.getService, tree)) {
+        const svcNode = match.captures.service;
+        if (!svcNode)
+            continue;
+        const svc = unquoteLiteral(svcNode.text);
+        if (!svc)
+            continue;
+        out.push({
+            role: 'consumer',
+            serviceName: svc,
+            symbolName: `${svc}Client`,
+            source: 'ts_client_grpc_get_service',
+            confidenceWithProto: 0.75,
+            confidenceWithoutProto: 0.55,
+        });
+    }
+    // ─── Consumer: new XxxServiceClient(...) ─────────────────────────
+    for (const match of runCompiledPatterns(bundle.newSimpleCtor, tree)) {
+        const ctorNode = match.captures.ctor;
+        if (!ctorNode)
+            continue;
+        const svcMatch = SERVICE_CLIENT_RE.exec(ctorNode.text);
+        if (!svcMatch)
+            continue;
+        const serviceName = svcMatch[1];
+        out.push({
+            role: 'consumer',
+            serviceName,
+            symbolName: `${serviceName}Client`,
+            source: 'ts_generated_client',
+            confidenceWithProto: 0.75,
+            confidenceWithoutProto: 0.55,
+        });
+    }
+    // ─── Consumer: loadPackageDefinition dynamic proto loader ────────
+    // Only emit when the file uses loadPackageDefinition, otherwise a
+    // generic `new foo.bar.Something()` in unrelated code would falsely
+    // register as a gRPC consumer. Check structurally via a dedicated
+    // query — avoids materializing `tree.rootNode.text` for the whole
+    // file (expensive on large files).
+    const usesLoadPackage = runCompiledPatterns(bundle.loadPackageDefinition, tree).length > 0;
+    if (usesLoadPackage) {
+        for (const match of runCompiledPatterns(bundle.newQualifiedCtor, tree)) {
+            const ctorNode = match.captures.ctor;
+            if (!ctorNode)
+                continue;
+            if (!CAPITALIZED_SERVICE_RE.test(ctorNode.text))
+                continue;
+            out.push({
+                role: 'consumer',
+                serviceName: ctorNode.text,
+                symbolName: `${ctorNode.text}Client`,
+                source: 'ts_load_package_definition',
+                confidenceWithProto: 0.75,
+                confidenceWithoutProto: 0.55,
+            });
+        }
+    }
+    return out;
+}
+export const JAVASCRIPT_GRPC_PLUGIN = {
+    name: 'javascript-grpc',
+    language: JavaScript,
+    scan: (tree) => scanBundle(JAVASCRIPT_BUNDLE, tree),
+};
+export const TYPESCRIPT_GRPC_PLUGIN = {
+    name: 'typescript-grpc',
+    language: TypeScript.typescript,
+    scan: (tree) => scanBundle(TYPESCRIPT_BUNDLE, tree),
+};
+export const TSX_GRPC_PLUGIN = {
+    name: 'tsx-grpc',
+    language: TypeScript.tsx,
+    scan: (tree) => scanBundle(TSX_BUNDLE, tree),
+};

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

@@ -0,0 +1,9 @@
+import type { GrpcLanguagePlugin } from './types.js';
+/**
+ * The proto plugin, or `null` if tree-sitter-proto is not available.
+ * The orchestrator checks this at import time and decides whether to
+ * use the tree-sitter path or the fallback manual parser.
+ */
+export declare const PROTO_GRPC_PLUGIN: GrpcLanguagePlugin | null;
+/** The package declaration text from a proto file's tree. */
+export declare function extractPackageFromTree(tree: import('tree-sitter').Tree): string;

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

@@ -0,0 +1,134 @@
+import { createRequire } from 'node:module';
+import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js';
+/**
+ * Protobuf (.proto) tree-sitter plugin for gRPC contract extraction.
+ *
+ * Uses `tree-sitter-proto` (coder3101/tree-sitter-proto) as an
+ * optionalDependency — if the grammar is not installed (e.g. native
+ * compilation failed on an unusual platform), the plugin exports
+ * `null` and the orchestrator falls back to the existing manual
+ * string-sanitizing parser.
+ *
+ * The grammar is vendored in `vendor/tree-sitter-proto/` with
+ * parser.c regenerated against tree-sitter-cli 0.24 (ABI version 14)
+ * so it is compatible with the project's tree-sitter 0.25 runtime.
+ */
+const _require = createRequire(import.meta.url);
+let ProtoGrammar = null;
+try {
+    ProtoGrammar = _require('tree-sitter-proto');
+}
+catch {
+    // Grammar not installed — PROTO_GRPC_PLUGIN will be null.
+}
+let PACKAGE_PATTERNS = null;
+let SERVICE_PATTERNS = null;
+if (ProtoGrammar) {
+    try {
+        // Validate that the grammar actually loads end-to-end: compile queries
+        // AND parse + walk a trivial proto file. tree-sitter's internal
+        // `initializeLanguageNodeClasses` can fail with a TDZ error in some
+        // test runners (vitest forks) when SyntaxNode isn't fully initialized
+        // yet. Catching that here ensures `PROTO_GRPC_PLUGIN` stays null and
+        // the orchestrator falls back to the manual parser.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const _Parser = _require('tree-sitter');
+        // Smoke-test: parse + setLanguage to verify the grammar is
+        // end-to-end compatible with this tree-sitter runtime.
+        const _testParser = new _Parser();
+        _testParser.setLanguage(ProtoGrammar);
+        _testParser.parse('service X { rpc Y (R) returns (R); }');
+        PACKAGE_PATTERNS = compilePatterns({
+            name: 'proto-package',
+            language: ProtoGrammar,
+            patterns: [
+                {
+                    meta: {},
+                    query: `(package (full_ident) @pkg)`,
+                },
+            ],
+        });
+        SERVICE_PATTERNS = compilePatterns({
+            name: 'proto-service',
+            language: ProtoGrammar,
+            patterns: [
+                {
+                    meta: {},
+                    query: `
+            (service
+              (service_name) @service_name
+              (rpc
+                (rpc_name) @rpc_name))
+          `,
+                },
+            ],
+        });
+    }
+    catch {
+        // Compilation failed (grammar ABI mismatch?) — fall back to null.
+        PACKAGE_PATTERNS = null;
+        SERVICE_PATTERNS = null;
+        ProtoGrammar = null;
+    }
+}
+function buildPlugin() {
+    if (!ProtoGrammar || !PACKAGE_PATTERNS || !SERVICE_PATTERNS)
+        return null;
+    const pkgPatterns = PACKAGE_PATTERNS;
+    const svcPatterns = SERVICE_PATTERNS;
+    return {
+        name: 'proto-grpc',
+        language: ProtoGrammar,
+        scan(tree) {
+            const out = [];
+            // Extract `package` declaration (first match wins).
+            let pkg = '';
+            for (const match of runCompiledPatterns(pkgPatterns, tree)) {
+                const pkgNode = match.captures.pkg;
+                if (pkgNode) {
+                    pkg = pkgNode.text;
+                    break;
+                }
+            }
+            // Extract `service → rpc` pairs. The query returns one match per
+            // (service, rpc) combination thanks to the nested structure.
+            for (const match of runCompiledPatterns(svcPatterns, tree)) {
+                const serviceNode = match.captures.service_name;
+                const rpcNode = match.captures.rpc_name;
+                if (!serviceNode || !rpcNode)
+                    continue;
+                const serviceName = serviceNode.text;
+                const methodName = rpcNode.text;
+                out.push({
+                    role: 'provider',
+                    serviceName,
+                    symbolName: `${serviceName}.${methodName}`,
+                    source: 'proto',
+                    methodName,
+                    // Proto definitions are the canonical source of truth — always
+                    // high confidence regardless of cross-referencing.
+                    confidenceWithProto: 0.85,
+                    confidenceWithoutProto: 0.85,
+                });
+            }
+            return out;
+        },
+    };
+}
+/**
+ * The proto plugin, or `null` if tree-sitter-proto is not available.
+ * The orchestrator checks this at import time and decides whether to
+ * use the tree-sitter path or the fallback manual parser.
+ */
+export const PROTO_GRPC_PLUGIN = buildPlugin();
+/** The package declaration text from a proto file's tree. */
+export function extractPackageFromTree(tree) {
+    if (!PACKAGE_PATTERNS)
+        return '';
+    for (const match of runCompiledPatterns(PACKAGE_PATTERNS, tree)) {
+        const pkgNode = match.captures.pkg;
+        if (pkgNode)
+            return pkgNode.text;
+    }
+    return '';
+}

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

@@ -0,0 +1,2 @@
+import type { GrpcLanguagePlugin } from './types.js';
+export declare const PYTHON_GRPC_PLUGIN: GrpcLanguagePlugin;