gitnexus 1.5.3 → 1.6.1

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;

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

@@ -0,0 +1,67 @@
+import Python from 'tree-sitter-python';
+import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js';
+/**
+ * Python gRPC plugin. Detects:
+ *   - Provider: `add_XxxServicer_to_server(...)` calls (bare identifier
+ *     or qualified attribute form `auth_pb2_grpc.add_XxxServicer_to_server`)
+ *   - Consumer: `XxxStub(channel)` calls (bare or `auth_pb2_grpc.XxxStub`)
+ */
+const ADD_SERVICER_RE = /^add_(\w+)Servicer_to_server$/;
+const STUB_RE = /^(\w+)Stub$/;
+/** Reserved names that would produce garbage service names. */
+const STUB_IGNORE = new Set(['Mock', 'Test', 'Fake', 'Stub']);
+// Any call whose target is either a bare identifier or an attribute
+// access (`obj.method`). The plugin filters the function name in JS.
+const CALL_PATTERNS = compilePatterns({
+    name: 'python-grpc-call',
+    language: Python,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call
+          function: [
+            (identifier) @fn
+            (attribute attribute: (identifier) @fn)
+          ])
+      `,
+        },
+    ],
+});
+export const PYTHON_GRPC_PLUGIN = {
+    name: 'python-grpc',
+    language: Python,
+    scan(tree) {
+        const out = [];
+        for (const match of runCompiledPatterns(CALL_PATTERNS, tree)) {
+            const fnNode = match.captures.fn;
+            if (!fnNode)
+                continue;
+            const fnText = fnNode.text;
+            const addServicer = ADD_SERVICER_RE.exec(fnText);
+            if (addServicer) {
+                out.push({
+                    role: 'provider',
+                    serviceName: addServicer[1],
+                    symbolName: fnText,
+                    source: 'python_servicer',
+                    confidenceWithProto: 0.8,
+                    confidenceWithoutProto: 0.65,
+                });
+                continue;
+            }
+            const stubMatch = STUB_RE.exec(fnText);
+            if (stubMatch && !STUB_IGNORE.has(stubMatch[1])) {
+                out.push({
+                    role: 'consumer',
+                    serviceName: stubMatch[1],
+                    symbolName: fnText,
+                    source: 'python_stub',
+                    confidenceWithProto: 0.75,
+                    confidenceWithoutProto: 0.55,
+                });
+            }
+        }
+        return out;
+    },
+};

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

@@ -0,0 +1,50 @@
+import type Parser from 'tree-sitter';
+/**
+ * Shared types for the grpc-extractor language plugins.
+ *
+ * Each plugin lives in its own file (java.ts, go.ts, ...) and owns the
+ * tree-sitter grammar import + query sources. The top-level
+ * `grpc-extractor.ts` orchestrator only knows about this type module
+ * and the plugin registry (`./index.ts`). It MUST NOT import any
+ * grammar or query text directly.
+ */
+export type GrpcRole = 'provider' | 'consumer';
+/**
+ * One raw gRPC detection produced by a plugin's `scan()` function. The
+ * orchestrator uses the proto map to resolve the full package-qualified
+ * contract id and choose a confidence based on whether the proto was
+ * found.
+ *
+ * Most patterns produce service-level detections; `TS @GrpcMethod` is
+ * the only pattern that captures an explicit `methodName`, producing
+ * a method-level contract (`grpc::pkg.Service/Method`).
+ */
+export interface GrpcDetection {
+    role: GrpcRole;
+    /** Short service name, e.g. `"AuthService"`. */
+    serviceName: string;
+    /** Symbol name emitted into the contract's symbolRef. */
+    symbolName: string;
+    /** Metadata source label (goes into `meta.source`). */
+    source: string;
+    /** Explicit method name; set only by TS `@GrpcMethod`. */
+    methodName?: string;
+    /** Confidence when the proto map resolves the service. */
+    confidenceWithProto: number;
+    /** Confidence when the proto map has no entry. */
+    confidenceWithoutProto: number;
+}
+/**
+ * One language-scoped gRPC plugin. Plugins own the tree-sitter grammar
+ * and a `scan(tree)` function that returns zero or more
+ * `GrpcDetection`s. The plugin is free to run multiple compiled query
+ * bundles and walk the AST to cross-reference captures.
+ *
+ * `language` is typed `unknown` for the same reason as in
+ * `tree-sitter-scanner.ts`.
+ */
+export interface GrpcLanguagePlugin {
+    name: string;
+    language: unknown;
+    scan(tree: Parser.Tree): GrpcDetection[];
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/core/group/extractors/http-patterns/go.d.ts

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

package/dist/core/group/extractors/http-patterns/go.js

@@ -0,0 +1,215 @@
+import Go from 'tree-sitter-go';
+import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
+/**
+ * Go HTTP plugin. Handles:
+ *   - gin / echo / chi framework routing — `r.GET("/path", handler)`
+ *   - net/http stdlib — `http.HandleFunc("/path", handler)`
+ *   - net/http consumer — `http.Get(...)`, `http.NewRequest("METHOD", ...)`
+ *   - resty consumer — `client.R().Delete("/path")`
+ */
+// ─── Provider: framework routing ──────────────────────────────────────
+// Matches `\w+\.GET(...)` etc. (gin, echo, chi all share this shape).
+// Captures the HTTP method (field name), path literal, and handler
+// identifier passed as the second argument.
+const FRAMEWORK_ROUTE_PATTERNS = compilePatterns({
+    name: 'go-framework-route',
+    language: Go,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call_expression
+          function: (selector_expression
+            field: (field_identifier) @http_method (#match? @http_method "^(GET|POST|PUT|DELETE|PATCH)$"))
+          arguments: (argument_list
+            (interpreted_string_literal) @path
+            (identifier) @handler))
+      `,
+        },
+    ],
+});
+// ─── Provider: net/http `http.HandleFunc("/p", handler)` ─────────────
+const HANDLE_FUNC_PATTERNS = compilePatterns({
+    name: 'go-handle-func',
+    language: Go,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call_expression
+          function: (selector_expression
+            operand: (identifier) @pkg (#eq? @pkg "http")
+            field: (field_identifier) @fn (#eq? @fn "HandleFunc"))
+          arguments: (argument_list
+            (interpreted_string_literal) @path
+            (identifier) @handler))
+      `,
+        },
+    ],
+});
+// ─── Consumer: net/http stdlib Get / Post / Head ─────────────────────
+const HTTP_CLIENT_METHOD_TO_HTTP = {
+    Get: 'GET',
+    Post: 'POST',
+    Head: 'GET', // HEAD has no body semantics we care about — treat as GET for contract matching
+};
+const HTTP_CLIENT_PATTERNS = compilePatterns({
+    name: 'go-http-client',
+    language: Go,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call_expression
+          function: (selector_expression
+            operand: (identifier) @pkg (#eq? @pkg "http")
+            field: (field_identifier) @fn (#match? @fn "^(Get|Post|Head)$"))
+          arguments: (argument_list . (interpreted_string_literal) @path))
+      `,
+        },
+    ],
+});
+// ─── Consumer: net/http `http.NewRequest("METHOD", "/path", ...)` ────
+const NEW_REQUEST_PATTERNS = compilePatterns({
+    name: 'go-new-request',
+    language: Go,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call_expression
+          function: (selector_expression
+            operand: (identifier) @pkg (#eq? @pkg "http")
+            field: (field_identifier) @fn (#eq? @fn "NewRequest"))
+          arguments: (argument_list
+            .
+            (interpreted_string_literal) @http_method
+            (interpreted_string_literal) @path))
+      `,
+        },
+    ],
+});
+// ─── Consumer: resty `client.R().Delete("/path")` ─────────────────────
+// Matches any chained call whose receiver is `something.R()` and whose
+// method name is an HTTP verb. This is how go-resty's fluent API looks.
+const RESTY_PATTERNS = compilePatterns({
+    name: 'go-resty',
+    language: Go,
+    patterns: [
+        {
+            meta: {},
+            query: `
+        (call_expression
+          function: (selector_expression
+            operand: (call_expression
+              function: (selector_expression
+                field: (field_identifier) @r (#eq? @r "R")))
+            field: (field_identifier) @http_method (#match? @http_method "^(Get|Post|Put|Delete|Patch)$"))
+          arguments: (argument_list . (interpreted_string_literal) @path))
+      `,
+        },
+    ],
+});
+export const GO_HTTP_PLUGIN = {
+    name: 'go-http',
+    language: Go,
+    scan(tree) {
+        const out = [];
+        // Framework providers: r.GET/POST/... with handler identifier
+        for (const match of runCompiledPatterns(FRAMEWORK_ROUTE_PATTERNS, tree)) {
+            const methodNode = match.captures.http_method;
+            const pathNode = match.captures.path;
+            const handlerNode = match.captures.handler;
+            if (!methodNode || !pathNode)
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            out.push({
+                role: 'provider',
+                framework: 'go-framework',
+                method: methodNode.text.toUpperCase(),
+                path,
+                name: handlerNode?.text ?? null,
+                confidence: 0.8,
+            });
+        }
+        // net/http HandleFunc: default method GET
+        for (const match of runCompiledPatterns(HANDLE_FUNC_PATTERNS, tree)) {
+            const pathNode = match.captures.path;
+            const handlerNode = match.captures.handler;
+            if (!pathNode)
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            out.push({
+                role: 'provider',
+                framework: 'go-stdlib',
+                method: 'GET',
+                path,
+                name: handlerNode?.text ?? null,
+                confidence: 0.8,
+            });
+        }
+        // net/http client: http.Get/Post/Head
+        for (const match of runCompiledPatterns(HTTP_CLIENT_PATTERNS, tree)) {
+            const fnNode = match.captures.fn;
+            const pathNode = match.captures.path;
+            if (!fnNode || !pathNode)
+                continue;
+            const httpMethod = HTTP_CLIENT_METHOD_TO_HTTP[fnNode.text];
+            if (!httpMethod)
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'go-stdlib',
+                method: httpMethod,
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
+        // net/http NewRequest
+        for (const match of runCompiledPatterns(NEW_REQUEST_PATTERNS, tree)) {
+            const methodNode = match.captures.http_method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const method = unquoteLiteral(methodNode.text);
+            const path = unquoteLiteral(pathNode.text);
+            if (method === null || path === null)
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'go-stdlib',
+                method: method.toUpperCase(),
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
+        // resty
+        for (const match of runCompiledPatterns(RESTY_PATTERNS, tree)) {
+            const methodNode = match.captures.http_method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const path = unquoteLiteral(pathNode.text);
+            if (path === null)
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'go-resty',
+                method: methodNode.text.toUpperCase(),
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
+        return out;
+    },
+};

package/dist/core/group/extractors/http-patterns/index.d.ts

@@ -0,0 +1,17 @@
+import type { HttpLanguagePlugin } from './types.js';
+export type { HttpDetection, HttpLanguagePlugin, HttpRole } from './types.js';
+/**
+ * Glob for files worth scanning for HTTP routes. Kept alongside the
+ * registry so adding a new language widens the glob in one edit.
+ *
+ * `.vue` / `.svelte` files are intentionally omitted for the source-scan
+ * path — they need their own grammar-aware extraction and the existing
+ * regex fallback for them was never very accurate. The graph-assisted
+ * Strategy A still handles them via the ingestion pipeline.
+ */
+export declare const HTTP_SCAN_GLOB = "**/*.{ts,tsx,js,jsx,java,go,py,php}";
+/**
+ * Return the HTTP plugin registered for the given file's extension,
+ * or `undefined` if the extension is not registered.
+ */
+export declare function getPluginForFile(rel: string): HttpLanguagePlugin | undefined;

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

@@ -0,0 +1,44 @@
+import * as path from 'node:path';
+import { JAVA_HTTP_PLUGIN } from './java.js';
+import { GO_HTTP_PLUGIN } from './go.js';
+import { PYTHON_HTTP_PLUGIN } from './python.js';
+import { PHP_HTTP_PLUGIN } from './php.js';
+import { JAVASCRIPT_HTTP_PLUGIN, TYPESCRIPT_HTTP_PLUGIN, TSX_HTTP_PLUGIN } from './node.js';
+/**
+ * File-extension → HTTP language plugin registry. The top-level
+ * orchestrator (`http-route-extractor.ts`) looks up the plugin for each
+ * file it visits and delegates the tree-sitter scanning to the plugin.
+ *
+ * Keys are lowercase extensions including the leading dot. To add a
+ * new language, drop a `http-patterns/<lang>.ts` that exports a
+ * `HttpLanguagePlugin`, import it here and register the extension(s).
+ * No edits to `http-route-extractor.ts` are required.
+ */
+const REGISTRY = {
+    '.java': JAVA_HTTP_PLUGIN,
+    '.go': GO_HTTP_PLUGIN,
+    '.py': PYTHON_HTTP_PLUGIN,
+    '.php': PHP_HTTP_PLUGIN,
+    '.js': JAVASCRIPT_HTTP_PLUGIN,
+    '.jsx': JAVASCRIPT_HTTP_PLUGIN,
+    '.ts': TYPESCRIPT_HTTP_PLUGIN,
+    '.tsx': TSX_HTTP_PLUGIN,
+};
+/**
+ * Glob for files worth scanning for HTTP routes. Kept alongside the
+ * registry so adding a new language widens the glob in one edit.
+ *
+ * `.vue` / `.svelte` files are intentionally omitted for the source-scan
+ * path — they need their own grammar-aware extraction and the existing
+ * regex fallback for them was never very accurate. The graph-assisted
+ * Strategy A still handles them via the ingestion pipeline.
+ */
+export const HTTP_SCAN_GLOB = '**/*.{ts,tsx,js,jsx,java,go,py,php}';
+/**
+ * Return the HTTP 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/http-patterns/java.d.ts

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