gitnexus 1.5.3 → 1.6.1

package/dist/core/group/bridge-schema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bridge LadybugDB schema for cross-repo Contract Registry.
+ * Separate from per-repo schema in lbug/schema.ts.
+ */
+/**
+ * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * this against `meta.json`'s version field and returns `null` on mismatch,
+ * which trips the caller into either the JSON fallback path or a fresh
+ * `group sync` that rebuilds `bridge.lbug` from scratch.
+ *
+ * Migration contract for contributors bumping this constant:
+ *   1. Bump the number (e.g. `1` → `2`).
+ *   2. Update the DDL below to match the new schema.
+ *   3. DO NOT attempt an online migration in this file — the version gate
+ *      is intentionally a "discard and re-sync" strategy for V1. An old
+ *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      rebuilt by the next `group sync`.
+ *   4. If online migration becomes necessary (e.g. when groups accumulate
+ *      large amounts of embedding data), add a migration path as a
+ *      separate `bridge-migrations.ts` module rather than bloating this
+ *      file — keep schema and migration concerns separate.
+ */
+export declare const BRIDGE_SCHEMA_VERSION = 1;
+export declare const CONTRACT_SCHEMA = "\nCREATE NODE TABLE Contract (\n  id STRING,\n  contractId STRING,\n  type STRING,\n  role STRING,\n  repo STRING,\n  service STRING DEFAULT '',\n  symbolUid STRING DEFAULT '',\n  filePath STRING DEFAULT '',\n  symbolName STRING DEFAULT '',\n  confidence DOUBLE DEFAULT 0.0,\n  meta STRING DEFAULT '{}',\n  PRIMARY KEY (id)\n)";
+export declare const REPO_SNAPSHOT_SCHEMA = "\nCREATE NODE TABLE RepoSnapshot (\n  id STRING,\n  indexedAt STRING DEFAULT '',\n  lastCommit STRING DEFAULT '',\n  PRIMARY KEY (id)\n)";
+export declare const CONTRACT_LINK_SCHEMA = "\nCREATE REL TABLE ContractLink (\n  FROM Contract TO Contract,\n  matchType STRING,\n  confidence DOUBLE,\n  contractId STRING,\n  fromRepo STRING,\n  toRepo STRING\n)";
+export declare const BRIDGE_SCHEMA_QUERIES: string[];

package/dist/core/group/bridge-schema.js

@@ -0,0 +1,55 @@
+/**
+ * Bridge LadybugDB schema for cross-repo Contract Registry.
+ * Separate from per-repo schema in lbug/schema.ts.
+ */
+/**
+ * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * this against `meta.json`'s version field and returns `null` on mismatch,
+ * which trips the caller into either the JSON fallback path or a fresh
+ * `group sync` that rebuilds `bridge.lbug` from scratch.
+ *
+ * Migration contract for contributors bumping this constant:
+ *   1. Bump the number (e.g. `1` → `2`).
+ *   2. Update the DDL below to match the new schema.
+ *   3. DO NOT attempt an online migration in this file — the version gate
+ *      is intentionally a "discard and re-sync" strategy for V1. An old
+ *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      rebuilt by the next `group sync`.
+ *   4. If online migration becomes necessary (e.g. when groups accumulate
+ *      large amounts of embedding data), add a migration path as a
+ *      separate `bridge-migrations.ts` module rather than bloating this
+ *      file — keep schema and migration concerns separate.
+ */
+export const BRIDGE_SCHEMA_VERSION = 1;
+export const CONTRACT_SCHEMA = `
+CREATE NODE TABLE Contract (
+  id STRING,
+  contractId STRING,
+  type STRING,
+  role STRING,
+  repo STRING,
+  service STRING DEFAULT '',
+  symbolUid STRING DEFAULT '',
+  filePath STRING DEFAULT '',
+  symbolName STRING DEFAULT '',
+  confidence DOUBLE DEFAULT 0.0,
+  meta STRING DEFAULT '{}',
+  PRIMARY KEY (id)
+)`;
+export const REPO_SNAPSHOT_SCHEMA = `
+CREATE NODE TABLE RepoSnapshot (
+  id STRING,
+  indexedAt STRING DEFAULT '',
+  lastCommit STRING DEFAULT '',
+  PRIMARY KEY (id)
+)`;
+export const CONTRACT_LINK_SCHEMA = `
+CREATE REL TABLE ContractLink (
+  FROM Contract TO Contract,
+  matchType STRING,
+  confidence DOUBLE,
+  contractId STRING,
+  fromRepo STRING,
+  toRepo STRING
+)`;
+export const BRIDGE_SCHEMA_QUERIES = [CONTRACT_SCHEMA, REPO_SNAPSHOT_SCHEMA, CONTRACT_LINK_SCHEMA];

package/dist/core/group/config-parser.d.ts

@@ -0,0 +1,3 @@
+import type { GroupConfig } from './types.js';
+export declare function parseGroupConfig(yamlContent: string): GroupConfig;
+export declare function loadGroupConfig(groupDir: string): Promise<GroupConfig>;

package/dist/core/group/config-parser.js

@@ -0,0 +1,83 @@
+import { createRequire } from 'node:module';
+const _require = createRequire(import.meta.url);
+const yaml = _require('js-yaml');
+const VALID_CONTRACT_TYPES = ['http', 'grpc', 'topic', 'lib', 'custom'];
+const VALID_ROLES = ['provider', 'consumer'];
+const DEFAULT_DETECT = {
+    http: true,
+    grpc: true,
+    topics: true,
+    shared_libs: true,
+    embedding_fallback: true,
+};
+const DEFAULT_MATCHING = {
+    bm25_threshold: 0.7,
+    embedding_threshold: 0.65,
+    max_candidates_per_step: 3,
+};
+export function parseGroupConfig(yamlContent) {
+    const raw = yaml.load(yamlContent, { schema: yaml.JSON_SCHEMA });
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Invalid YAML: expected an object');
+    }
+    if (raw.version === undefined)
+        throw new Error('version is required in group.yaml');
+    if (raw.version !== 1) {
+        throw new Error(`Unsupported group.yaml version: ${raw.version}. Expected 1.`);
+    }
+    if (!raw.name || typeof raw.name !== 'string')
+        throw new Error('name is required in group.yaml');
+    if (!raw.repos || typeof raw.repos !== 'object' || Array.isArray(raw.repos)) {
+        throw new Error('repos is required in group.yaml (must be a mapping)');
+    }
+    const repos = raw.repos;
+    const repoPaths = new Set(Object.keys(repos));
+    const rawLinks = raw.links || [];
+    const links = rawLinks.map((l, i) => {
+        const link = l;
+        if (!link.from || !repoPaths.has(link.from)) {
+            throw new Error(`links[${i}].from "${link.from}" does not match any repo path in group`);
+        }
+        if (!link.to || !repoPaths.has(link.to)) {
+            throw new Error(`links[${i}].to "${link.to}" does not match any repo path in group`);
+        }
+        if (!VALID_CONTRACT_TYPES.includes(link.type)) {
+            throw new Error(`links[${i}].type "${link.type}" is invalid. Expected: ${VALID_CONTRACT_TYPES.join(', ')}`);
+        }
+        if (!VALID_ROLES.includes(link.role)) {
+            throw new Error(`links[${i}].role "${link.role}" is invalid. Expected: provider | consumer`);
+        }
+        if (link.contract === undefined ||
+            link.contract === null ||
+            String(link.contract).trim() === '') {
+            throw new Error(`links[${i}].contract is required`);
+        }
+        return {
+            from: link.from,
+            to: link.to,
+            type: link.type,
+            contract: String(link.contract),
+            role: link.role,
+        };
+    });
+    const detect = { ...DEFAULT_DETECT, ...(raw.detect || {}) };
+    const matching = { ...DEFAULT_MATCHING, ...(raw.matching || {}) };
+    const packages = raw.packages || {};
+    return {
+        version: 1,
+        name: raw.name,
+        description: raw.description || '',
+        repos,
+        links,
+        packages,
+        detect,
+        matching,
+    };
+}
+export async function loadGroupConfig(groupDir) {
+    const fsp = await import('node:fs/promises');
+    const path = await import('node:path');
+    const yamlPath = path.join(groupDir, 'group.yaml');
+    const content = await fsp.readFile(yamlPath, 'utf-8');
+    return parseGroupConfig(content);
+}

package/dist/core/group/contract-extractor.d.ts

@@ -0,0 +1,7 @@
+import type { ContractType, ExtractedContract, RepoHandle } from './types.js';
+export interface ContractExtractor {
+    type: ContractType;
+    canExtract(repo: RepoHandle): Promise<boolean>;
+    extract(dbExecutor: CypherExecutor | null, repoPath: string, repo: RepoHandle): Promise<ExtractedContract[]>;
+}
+export type CypherExecutor = (query: string, params?: Record<string, unknown>) => Promise<Record<string, unknown>[]>;

package/dist/core/group/contract-extractor.js

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

package/dist/core/group/extractors/fs-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Safely read a file inside a repo, rejecting any path that escapes
+ * `repoPath` via `..` traversal or absolute segments. Returns `null` if
+ * the path is outside the repo or the file can't be read.
+ *
+ * Used by every source-scan extractor under this directory. Kept as a
+ * single shared implementation so the path-traversal guard (security-
+ * sensitive) lives in exactly one place.
+ */
+export declare function readSafe(repoPath: string, rel: string): string | null;

package/dist/core/group/extractors/fs-utils.js

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Safely read a file inside a repo, rejecting any path that escapes
+ * `repoPath` via `..` traversal or absolute segments. Returns `null` if
+ * the path is outside the repo or the file can't be read.
+ *
+ * Used by every source-scan extractor under this directory. Kept as a
+ * single shared implementation so the path-traversal guard (security-
+ * sensitive) lives in exactly one place.
+ */
+export function readSafe(repoPath, rel) {
+    const abs = path.resolve(repoPath, rel);
+    const base = path.resolve(repoPath);
+    const relToBase = path.relative(base, abs);
+    if (relToBase.startsWith('..') || path.isAbsolute(relToBase))
+        return null;
+    try {
+        return fs.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
+import type { ExtractedContract, RepoHandle } from '../types.js';
+export interface ProtoServiceInfo {
+    package: string;
+    serviceName: string;
+    methods: string[];
+    protoPath: string;
+}
+export declare function buildProtoMap(repoPath: string): Promise<Map<string, ProtoServiceInfo[]>>;
+export declare function resolveProtoConflict(_serviceName: string, sourceFilePath: string, candidates: ProtoServiceInfo[]): ProtoServiceInfo | null;
+export declare function serviceContractId(pkg: string, serviceName: string): string;
+export declare class GrpcExtractor implements ContractExtractor {
+    type: "grpc";
+    canExtract(_repo: RepoHandle): Promise<boolean>;
+    extract(_dbExecutor: CypherExecutor | null, repoPath: string, _repo: RepoHandle): Promise<ExtractedContract[]>;
+    /**
+     * Convert a plugin `GrpcDetection` into a concrete `ExtractedContract`
+     * by resolving the short service name against the proto map, building
+     * 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.
+     */
+    private detectionToContract;
+    private dedupe;
+}

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

@@ -0,0 +1,386 @@
+import * as path from 'node:path';
+import { glob } from 'glob';
+import Parser from 'tree-sitter';
+import { readSafe } from './fs-utils.js';
+import { GRPC_SCAN_GLOB, getPluginForFile, hasProtoPlugin, } from './grpc-patterns/index.js';
+/**
+ * Language-agnostic orchestrator for gRPC (provider + consumer) contract
+ * extraction.
+ *
+ * Two parts:
+ *
+ * 1. **`.proto` parsing** — tree-sitter when `tree-sitter-proto` is
+ *    installed (optionalDependency vendored in `vendor/tree-sitter-proto/`),
+ *    via the `.proto` entry in `grpc-patterns/` and `hasProtoPlugin`.
+ *    When the grammar isn't available (platform incompatibility, native
+ *    build failure) the orchestrator falls back to the in-process
+ *    string-sanitizing parser defined below (`stripProtoCommentsAndStrings`
+ *    + `extractServiceBlocks`). The fallback preserves offsets so any
+ *    downstream regex scans run against a sanitized copy without
+ *    affecting line numbers of the original.
+ *
+ * 2. **Source-scan providers / consumers** — delegated to per-language
+ *    plugins in `./grpc-patterns/`. The orchestrator imports NO
+ *    tree-sitter grammars or query strings — each plugin owns its own.
+ */
+// ─── .proto fallback parser (used only when tree-sitter-proto is absent) ───
+function contractId(pkg, service, method) {
+    const prefix = pkg ? `${pkg}.${service}` : service;
+    return `grpc::${prefix}/${method}`;
+}
+function serviceOnlyContractId(serviceName) {
+    return `grpc::${serviceName}/*`;
+}
+/**
+ * Replace all .proto comments and string literals with spaces, preserving the
+ * original length and character offsets of the input. This lets downstream
+ * regex / brace-depth parsers run on a "sanitized" copy without having to
+ * understand proto syntax, while any RegExp.exec/index-based lookups that
+ * were already positional against `content` continue to work against the
+ * original string.
+ *
+ * Supported comment forms: `// line comment`, `/* block comment * /`.
+ * Supported strings: double-quoted ("…") and single-quoted ('…') with `\`
+ * escape handling. Raw/unterminated strings are not supported — we stop
+ * on a line break for line-style comments and on EOF for unterminated
+ * strings/blocks, which matches how most real proto files parse.
+ */
+function stripProtoCommentsAndStrings(content) {
+    const out = new Array(content.length);
+    let i = 0;
+    while (i < content.length) {
+        const ch = content[i];
+        const next = content[i + 1];
+        // Line comment: // ... \n
+        if (ch === '/' && next === '/') {
+            out[i] = ' ';
+            out[i + 1] = ' ';
+            i += 2;
+            while (i < content.length && content[i] !== '\n') {
+                out[i] = content[i] === '\r' ? '\r' : ' ';
+                i++;
+            }
+            continue;
+        }
+        // Block comment: /* ... */
+        if (ch === '/' && next === '*') {
+            out[i] = ' ';
+            out[i + 1] = ' ';
+            i += 2;
+            while (i < content.length) {
+                if (content[i] === '*' && content[i + 1] === '/') {
+                    out[i] = ' ';
+                    out[i + 1] = ' ';
+                    i += 2;
+                    break;
+                }
+                // Preserve newlines so line numbers stay stable for downstream code.
+                out[i] = content[i] === '\n' || content[i] === '\r' ? content[i] : ' ';
+                i++;
+            }
+            continue;
+        }
+        // String literal: "..." or '...'
+        if (ch === '"' || ch === "'") {
+            const quote = ch;
+            out[i] = ' '; // replace opening quote
+            i++;
+            while (i < content.length) {
+                const c = content[i];
+                if (c === '\\' && i + 1 < content.length) {
+                    // Skip escaped pair (e.g. \" \n \\)
+                    out[i] = ' ';
+                    out[i + 1] = ' ';
+                    i += 2;
+                    continue;
+                }
+                if (c === quote) {
+                    out[i] = ' ';
+                    i++;
+                    break;
+                }
+                // Preserve newlines; proto technically disallows unescaped newlines
+                // inside strings, but real files occasionally have them.
+                out[i] = c === '\n' || c === '\r' ? c : ' ';
+                i++;
+            }
+            continue;
+        }
+        out[i] = ch;
+        i++;
+    }
+    return out.join('');
+}
+function extractServiceBlocks(content) {
+    const results = [];
+    // Sanitize comments and string literals so braces inside them don't
+    // throw off the depth counter. The sanitized copy has the same length
+    // and offsets as the original, so we use it ONLY to scan for service
+    // headers and braces; the service body we return is sliced from the
+    // ORIGINAL content to preserve exact source text for downstream use.
+    const sanitized = stripProtoCommentsAndStrings(content);
+    const headerRe = /service\s+(\w+)\s*\{/g;
+    let headerMatch;
+    while ((headerMatch = headerRe.exec(sanitized)) !== null) {
+        const serviceName = headerMatch[1];
+        const bodyStart = headerMatch.index + headerMatch[0].length;
+        let depth = 1;
+        let pos = bodyStart;
+        while (pos < sanitized.length && depth > 0) {
+            const ch = sanitized[pos];
+            if (ch === '{')
+                depth++;
+            else if (ch === '}')
+                depth--;
+            pos++;
+        }
+        // If EOF before depth returns to 0, skip incomplete service
+        if (depth !== 0)
+            continue;
+        // body is between opening { (consumed by regex) and closing } (pos is one past it)
+        const body = content.slice(bodyStart, pos - 1);
+        results.push({ name: serviceName, body });
+    }
+    return results;
+}
+function makeContract(cid, role, filePath, symbolName, confidence, meta) {
+    return {
+        contractId: cid,
+        type: 'grpc',
+        role,
+        symbolUid: '',
+        symbolRef: { filePath: filePath.replace(/\\/g, '/'), name: symbolName },
+        symbolName,
+        confidence,
+        meta: { ...meta, extractionStrategy: 'source_scan' },
+    };
+}
+function normalizeProtoPath(rel) {
+    return rel.replace(/\\/g, '/');
+}
+function extractProtoImports(content) {
+    const imports = [];
+    const re = /^\s*import\s+"([^"]+)"\s*;/gm;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        imports.push(match[1]);
+    }
+    return imports;
+}
+function longestSharedSegmentRun(aPath, bPath) {
+    const a = aPath.split('/').filter(Boolean);
+    const b = bPath.split('/').filter(Boolean);
+    let best = 0;
+    for (let i = 0; i < a.length; i++) {
+        for (let j = 0; j < b.length; j++) {
+            let run = 0;
+            while (a[i + run] && b[j + run] && a[i + run] === b[j + run]) {
+                run++;
+            }
+            if (run > best)
+                best = run;
+        }
+    }
+    return best;
+}
+async function buildProtoContext(repoPath) {
+    const servicesByName = new Map();
+    const protoFiles = await glob('**/*.proto', {
+        cwd: repoPath,
+        absolute: false,
+        nodir: true,
+        ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**'],
+    });
+    const contents = new Map();
+    for (const rel of protoFiles) {
+        const content = readSafe(repoPath, rel);
+        if (!content)
+            continue;
+        contents.set(normalizeProtoPath(rel), content);
+    }
+    const packagesByProto = new Map();
+    const resolvePackage = (protoPath, seen = new Set()) => {
+        if (packagesByProto.has(protoPath))
+            return packagesByProto.get(protoPath) ?? '';
+        if (seen.has(protoPath))
+            return '';
+        const content = contents.get(protoPath);
+        if (!content)
+            return '';
+        seen.add(protoPath);
+        const pkgMatch = content.match(/^\s*package\s+([\w.]+)\s*;/m);
+        if (pkgMatch?.[1]) {
+            packagesByProto.set(protoPath, pkgMatch[1]);
+            return pkgMatch[1];
+        }
+        for (const importPath of extractProtoImports(content)) {
+            const normalizedImport = normalizeProtoPath(importPath);
+            const candidates = [
+                normalizeProtoPath(path.posix.normalize(path.posix.join(path.posix.dirname(protoPath), normalizedImport))),
+                normalizedImport,
+            ];
+            for (const candidate of candidates) {
+                if (!contents.has(candidate))
+                    continue;
+                const inheritedPackage = resolvePackage(candidate, seen);
+                if (inheritedPackage) {
+                    packagesByProto.set(protoPath, inheritedPackage);
+                    return inheritedPackage;
+                }
+            }
+        }
+        packagesByProto.set(protoPath, '');
+        return '';
+    };
+    for (const rel of protoFiles) {
+        const normalizedRel = normalizeProtoPath(rel);
+        const content = contents.get(normalizedRel);
+        if (!content)
+            continue;
+        const pkg = resolvePackage(normalizedRel);
+        const serviceBlocks = extractServiceBlocks(content);
+        for (const block of serviceBlocks) {
+            const rpcRe = /rpc\s+(\w+)\s*\(/g;
+            const methods = [];
+            let m;
+            while ((m = rpcRe.exec(block.body)) !== null) {
+                methods.push(m[1]);
+            }
+            const info = {
+                package: pkg,
+                serviceName: block.name,
+                methods,
+                protoPath: normalizedRel,
+            };
+            const existing = servicesByName.get(block.name) ?? [];
+            existing.push(info);
+            servicesByName.set(block.name, existing);
+        }
+    }
+    return { packagesByProto, servicesByName };
+}
+export async function buildProtoMap(repoPath) {
+    const { servicesByName } = await buildProtoContext(repoPath);
+    return servicesByName;
+}
+export function resolveProtoConflict(_serviceName, sourceFilePath, candidates) {
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0];
+    const sourceDir = normalizeProtoPath(path.dirname(sourceFilePath));
+    let best = candidates[0];
+    let bestScore = -1;
+    for (const c of candidates) {
+        const protoDir = normalizeProtoPath(path.dirname(c.protoPath));
+        const sharedRun = longestSharedSegmentRun(sourceDir, protoDir);
+        if (sharedRun > bestScore) {
+            bestScore = sharedRun;
+            best = c;
+        }
+    }
+    return best;
+}
+export function serviceContractId(pkg, serviceName) {
+    const prefix = pkg ? `${pkg}.${serviceName}` : serviceName;
+    return `grpc::${prefix}/*`;
+}
+// ─── Orchestrator ────────────────────────────────────────────────────
+export class GrpcExtractor {
+    type = 'grpc';
+    async canExtract(_repo) {
+        return true;
+    }
+    async extract(_dbExecutor, repoPath, _repo) {
+        const out = [];
+        const protoContext = await buildProtoContext(repoPath);
+        const protoMap = protoContext.servicesByName;
+        // ─── 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
+        // emit provider contracts directly from the proto map that
+        // `buildProtoContext` already built — no second glob / parse pass.
+        if (!hasProtoPlugin) {
+            for (const infos of protoMap.values()) {
+                for (const info of infos) {
+                    for (const methodName of info.methods) {
+                        const cid = contractId(info.package, info.serviceName, methodName);
+                        out.push(makeContract(cid, 'provider', info.protoPath, `${info.serviceName}.${methodName}`, 0.85, {
+                            package: info.package,
+                            service: info.serviceName,
+                            method: methodName,
+                            source: 'proto',
+                        }));
+                    }
+                }
+            }
+        }
+        // ─── Source files (+ .proto when plugin available) ────────────
+        const sourceFiles = await glob(GRPC_SCAN_GLOB, {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'],
+            nodir: true,
+        });
+        const parser = new Parser();
+        for (const rel of sourceFiles) {
+            const plugin = getPluginForFile(rel);
+            if (!plugin)
+                continue;
+            const content = readSafe(repoPath, rel);
+            if (!content)
+                continue;
+            let detections = [];
+            try {
+                parser.setLanguage(plugin.language);
+                const tree = parser.parse(content);
+                detections = plugin.scan(tree);
+            }
+            catch {
+                continue;
+            }
+            for (const d of detections) {
+                out.push(this.detectionToContract(d, rel, protoMap));
+            }
+        }
+        return this.dedupe(out);
+    }
+    /**
+     * Convert a plugin `GrpcDetection` into a concrete `ExtractedContract`
+     * by resolving the short service name against the proto map, building
+     * 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.
+     */
+    detectionToContract(d, filePath, protoMap) {
+        const candidates = protoMap.get(d.serviceName);
+        const proto = resolveProtoConflict(d.serviceName, filePath, candidates ?? []);
+        const pkg = proto?.package ?? '';
+        const cid = d.methodName
+            ? contractId(pkg, d.serviceName, d.methodName)
+            : proto
+                ? serviceContractId(pkg, d.serviceName)
+                : serviceOnlyContractId(d.serviceName);
+        const confidence = proto ? d.confidenceWithProto : d.confidenceWithoutProto;
+        const meta = {
+            service: d.serviceName,
+            source: d.source,
+        };
+        if (d.methodName)
+            meta.method = d.methodName;
+        return makeContract(cid, d.role, filePath, d.symbolName, confidence, meta);
+    }
+    dedupe(items) {
+        const byKey = new Map();
+        for (const c of items) {
+            const k = `${c.contractId}|${c.role}|${c.symbolRef.filePath}`;
+            const existing = byKey.get(k);
+            if (!existing ||
+                c.confidence > existing.confidence ||
+                (c.confidence === existing.confidence &&
+                    String(c.meta.source) < String(existing.meta.source))) {
+                byKey.set(k, c);
+            }
+        }
+        return Array.from(byKey.values());
+    }
+}

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

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