gitnexus 1.5.3 → 1.6.0

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/grpc-extractor.d.ts

@@ -0,0 +1,16 @@
+import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
+import type { ExtractedContract, RepoHandle } from '../types.js';
+export declare class GrpcExtractor implements ContractExtractor {
+    type: "grpc";
+    canExtract(_repo: RepoHandle): Promise<boolean>;
+    extract(_dbExecutor: CypherExecutor | null, repoPath: string, _repo: RepoHandle): Promise<ExtractedContract[]>;
+    private parseProtoFile;
+    private scanGoProviders;
+    private scanGoConsumers;
+    private scanJavaProviders;
+    private scanJavaConsumers;
+    private scanPythonProviders;
+    private scanPythonConsumers;
+    private scanTsProviders;
+    private dedupe;
+}

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

@@ -0,0 +1,264 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { glob } from 'glob';
+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;
+    }
+}
+function contractId(pkg, service, method) {
+    const prefix = pkg ? `${pkg}.${service}` : service;
+    return `grpc::${prefix}/${method}`;
+}
+function serviceOnlyContractId(serviceName) {
+    return `grpc::${serviceName}/*`;
+}
+function extractServiceBlocks(content) {
+    const results = [];
+    // v1: brace-depth only — braces inside comments or string literals are not filtered (see spec Fix 2)
+    const headerRe = /service\s+(\w+)\s*\{/g;
+    let headerMatch;
+    while ((headerMatch = headerRe.exec(content)) !== null) {
+        const serviceName = headerMatch[1];
+        const bodyStart = headerMatch.index + headerMatch[0].length;
+        let depth = 1;
+        let pos = bodyStart;
+        while (pos < content.length && depth > 0) {
+            const ch = content[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' },
+    };
+}
+export class GrpcExtractor {
+    type = 'grpc';
+    async canExtract(_repo) {
+        return true;
+    }
+    async extract(_dbExecutor, repoPath, _repo) {
+        const out = [];
+        // Proto files — definitive provider source
+        const protoFiles = await glob('**/*.proto', {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**'],
+            nodir: true,
+        });
+        for (const rel of protoFiles) {
+            const content = readSafe(repoPath, rel);
+            if (content)
+                out.push(...this.parseProtoFile(content, rel));
+        }
+        // Source files — server/client detection
+        const sourceFiles = await glob('**/*.{go,java,py,ts,tsx,js,jsx}', {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'],
+            nodir: true,
+        });
+        for (const rel of sourceFiles) {
+            const content = readSafe(repoPath, rel);
+            if (!content)
+                continue;
+            const ext = path.extname(rel).toLowerCase();
+            if (ext === '.go') {
+                out.push(...this.scanGoProviders(content, rel));
+                out.push(...this.scanGoConsumers(content, rel));
+            }
+            else if (ext === '.java') {
+                out.push(...this.scanJavaProviders(content, rel));
+                out.push(...this.scanJavaConsumers(content, rel));
+            }
+            else if (ext === '.py') {
+                out.push(...this.scanPythonProviders(content, rel));
+                out.push(...this.scanPythonConsumers(content, rel));
+            }
+            else if (['.ts', '.tsx', '.js', '.jsx'].includes(ext)) {
+                out.push(...this.scanTsProviders(content, rel));
+            }
+        }
+        return this.dedupe(out);
+    }
+    parseProtoFile(content, filePath) {
+        const out = [];
+        const pkgMatch = content.match(/^package\s+([\w.]+)\s*;/m);
+        const pkg = pkgMatch ? pkgMatch[1] : '';
+        for (const { name: serviceName, body } of extractServiceBlocks(content)) {
+            const rpcRe = /rpc\s+(\w+)\s*\(/g;
+            let rpcMatch;
+            while ((rpcMatch = rpcRe.exec(body)) !== null) {
+                const methodName = rpcMatch[1];
+                const cid = contractId(pkg, serviceName, methodName);
+                out.push(makeContract(cid, 'provider', filePath, `${serviceName}.${methodName}`, 0.85, {
+                    package: pkg,
+                    service: serviceName,
+                    method: methodName,
+                    source: 'proto',
+                }));
+            }
+        }
+        return out;
+    }
+    scanGoProviders(content, filePath) {
+        const out = [];
+        // pb.RegisterXxxServer(
+        const registerRe = /\w+\.Register(\w+)Server\s*\(/g;
+        let m;
+        while ((m = registerRe.exec(content)) !== null) {
+            const serviceName = m[1];
+            out.push(makeContract(serviceOnlyContractId(serviceName), 'provider', filePath, `Register${serviceName}Server`, 0.8, { service: serviceName, source: 'go_register' }));
+        }
+        // pb.UnimplementedXxxServer
+        const unimplRe = /\w+\.Unimplemented(\w+)Server\b/g;
+        while ((m = unimplRe.exec(content)) !== null) {
+            const serviceName = m[1];
+            out.push(makeContract(serviceOnlyContractId(serviceName), 'provider', filePath, `Unimplemented${serviceName}Server`, 0.8, { service: serviceName, source: 'go_unimplemented' }));
+        }
+        return out;
+    }
+    scanGoConsumers(content, filePath) {
+        const out = [];
+        const re = /\w+\.New(\w+)Client\s*\(/g;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const serviceName = m[1];
+            out.push(makeContract(serviceOnlyContractId(serviceName), 'consumer', filePath, `New${serviceName}Client`, 0.7, { service: serviceName, source: 'go_client' }));
+        }
+        return out;
+    }
+    scanJavaProviders(content, filePath) {
+        const out = [];
+        // @GrpcService
+        if (content.includes('@GrpcService')) {
+            const implBaseRe = /extends\s+(\w+)Grpc\.(\w+)ImplBase/;
+            const m = content.match(implBaseRe);
+            if (m) {
+                out.push(makeContract(serviceOnlyContractId(m[1]), 'provider', filePath, m[2], 0.8, {
+                    service: m[1],
+                    source: 'java_grpc_service',
+                }));
+            }
+            else {
+                // Try extracting service name from class name
+                const classRe = /class\s+(\w*?)(?:Grpc)?(?:Service)?\s+extends\s+(\w+)(?:Grpc\.(\w+))?ImplBase/;
+                const cm = content.match(classRe);
+                if (cm) {
+                    const svcName = cm[2].replace(/Grpc$/, '');
+                    out.push(makeContract(serviceOnlyContractId(svcName), 'provider', filePath, cm[1], 0.8, {
+                        service: svcName,
+                        source: 'java_grpc_service',
+                    }));
+                }
+            }
+        }
+        // extends XxxImplBase (without @GrpcService)
+        if (!content.includes('@GrpcService')) {
+            const implRe = /extends\s+(\w+?)(?:Grpc\.(\w+))?ImplBase/;
+            const m = content.match(implRe);
+            if (m) {
+                const svcName = m[2] || m[1].replace(/Grpc$/, '');
+                out.push(makeContract(serviceOnlyContractId(svcName), 'provider', filePath, svcName, 0.8, {
+                    service: svcName,
+                    source: 'java_impl_base',
+                }));
+            }
+        }
+        return out;
+    }
+    scanJavaConsumers(content, filePath) {
+        const out = [];
+        // XxxGrpc.newBlockingStub( or XxxGrpc.newStub(
+        const re = /(\w+)Grpc\.new(?:Blocking)?Stub\s*\(/g;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const serviceName = m[1];
+            out.push(makeContract(serviceOnlyContractId(serviceName), 'consumer', filePath, `${serviceName}Stub`, 0.7, { service: serviceName, source: 'java_stub' }));
+        }
+        return out;
+    }
+    scanPythonProviders(content, filePath) {
+        const out = [];
+        // add_XxxServicer_to_server(
+        const re = /add_(\w+?)Servicer_to_server\s*\(/g;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const serviceName = m[1];
+            out.push(makeContract(serviceOnlyContractId(serviceName), 'provider', filePath, `add_${serviceName}Servicer_to_server`, 0.8, { service: serviceName, source: 'python_servicer' }));
+        }
+        return out;
+    }
+    scanPythonConsumers(content, filePath) {
+        const out = [];
+        // XxxStub(
+        const re = /(\w+)Stub\s*\(/g;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const name = m[1];
+            // Filter out common false positives
+            if (['Mock', 'Test', 'Fake', 'Stub'].includes(name))
+                continue;
+            out.push(makeContract(serviceOnlyContractId(name), 'consumer', filePath, `${name}Stub`, 0.7, {
+                service: name,
+                source: 'python_stub',
+            }));
+        }
+        return out;
+    }
+    scanTsProviders(content, filePath) {
+        const out = [];
+        // @GrpcMethod('ServiceName', 'MethodName')
+        const re = /@GrpcMethod\s*\(\s*['"](\w+)['"]\s*,\s*['"](\w+)['"]\s*\)/g;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const serviceName = m[1];
+            const methodName = m[2];
+            const cid = contractId('', serviceName, methodName);
+            out.push(makeContract(cid, 'provider', filePath, `${serviceName}.${methodName}`, 0.8, {
+                service: serviceName,
+                method: methodName,
+                source: 'ts_grpc_method',
+            }));
+        }
+        return out;
+    }
+    dedupe(items) {
+        const seen = new Set();
+        const out = [];
+        for (const c of items) {
+            const k = `${c.contractId}|${c.role}|${c.symbolRef.filePath}`;
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(c);
+        }
+        return out;
+    }
+}

package/dist/core/group/extractors/http-route-extractor.d.ts

@@ -0,0 +1,24 @@
+import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
+import type { ExtractedContract, RepoHandle } from '../types.js';
+export declare function normalizeHttpPath(p: string): string;
+export declare class HttpRouteExtractor implements ContractExtractor {
+    type: "http";
+    canExtract(_repo: RepoHandle): Promise<boolean>;
+    extract(dbExecutor: CypherExecutor | null, repoPath: string, repo: RepoHandle): Promise<ExtractedContract[]>;
+    private extractProvidersGraph;
+    private inferMethodFromFileScan;
+    private extractProvidersSourceScan;
+    private dedupeContracts;
+    private scanSpringProviders;
+    private scanExpressProviders;
+    private scanLaravelProviders;
+    private scanFastApiProviders;
+    private makeProvider;
+    private extractConsumersGraph;
+    private inferFetchMethod;
+    private extractConsumersSourceScan;
+    private scanFetchConsumers;
+    private templateToPattern;
+    private scanAxiosConsumers;
+    private makeConsumer;
+}