gitnexus 1.6.0 → 1.6.2-rc.1

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

@@ -0,0 +1,277 @@
+/**
+ * Canonicalize an HTTP path for matching against Route.name in the graph.
+ * Mirrors core/ingestion/pipeline.ts ensureSlash semantics:
+ * - Ensures a leading slash.
+ * - Strips trailing slashes (except the root "/").
+ * - Normalizes consecutive slashes.
+ * - Does NOT lowercase (route matching is case-sensitive).
+ */
+function normalizeRoutePath(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return '/';
+    const withLeading = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    const collapsed = withLeading.replace(/\/+/g, '/');
+    if (collapsed === '/')
+        return '/';
+    return collapsed.replace(/\/+$/, '');
+}
+/**
+ * Split a manifest HTTP contract into its optional `METHOD::` prefix and
+ * its path portion.
+ *
+ * `buildContractId` recommends the explicit-method form `GET::/api/orders`
+ * in group.yaml; if we hand that raw string to `normalizeRoutePath` we get
+ * `/GET::/api/orders`, which can never match `Route.name = "/api/orders"`
+ * in the graph. This helper extracts the path portion so the Cypher
+ * lookup uses the canonical route name.
+ *
+ * The method prefix regex mirrors `buildContractId` (line ~251) for
+ * symmetry: case-insensitive `[A-Za-z]+` followed by `::`. The captured
+ * method is upper-cased for downstream use; method-constrained matching
+ * against `HANDLES_ROUTE` is a future enhancement (not yet wired).
+ *
+ * Edge cases:
+ *  - `"::/api/orders"` — empty method portion, no alpha prefix match, so
+ *    the whole string is treated as a bare path (matches buildContractId
+ *    which also requires `[A-Za-z]+`).
+ *  - `"GET::"` — method with empty path, returns `{ method: 'GET', path: '' }`;
+ *    `normalizeRoutePath('')` resolves to `/` for caller.
+ */
+function parseHttpContract(raw) {
+    const match = raw.match(/^([A-Za-z]+)::/);
+    if (!match)
+        return { method: null, path: raw };
+    return { method: match[1].toUpperCase(), path: raw.slice(match[0].length) };
+}
+/**
+ * Stable synthetic symbolUid for a manifest-declared contract whose target
+ * symbol could not be resolved against the per-repo graph (resolveSymbol
+ * returned null). Two reasons we don't leave the uid empty:
+ *
+ *  1. The bridge stores Contract nodes keyed in part by symbolUid; an empty
+ *     uid means downstream Cypher queries that anchor on `provider.symbolUid`
+ *     can't tell two different unresolved manifest contracts apart.
+ *  2. The cross-impact bridge query in cross-impact.ts joins local impact
+ *     results to bridge contracts via `WHERE provider.symbolUid IN $localUids`.
+ *     If the local impact engine produces a deterministic identifier for the
+ *     unresolved target, it must agree with the value the bridge stored. A
+ *     synthetic uid keyed off (repo, contractId) is the only thing both sides
+ *     can derive without knowing about each other.
+ *
+ * Format: `manifest::<repo>::<contractId>`. Stable across syncs, scoped to a
+ * single repo within a group, and never collides with real indexer uids
+ * (which never start with `manifest::`).
+ */
+export function manifestSymbolUid(repo, contractId) {
+    return `manifest::${repo}::${contractId}`;
+}
+export class ManifestExtractor {
+    async extractFromManifest(links, dbExecutors) {
+        const contracts = [];
+        const crossLinks = [];
+        for (const link of links) {
+            const contractId = this.buildContractId(link.type, link.contract);
+            const providerRepo = link.role === 'provider' ? link.from : link.to;
+            const consumerRepo = link.role === 'provider' ? link.to : link.from;
+            const providerSymbol = await this.resolveSymbol(providerRepo, link, dbExecutors);
+            const consumerSymbol = await this.resolveSymbol(consumerRepo, link, dbExecutors);
+            const providerRef = providerSymbol || { filePath: '', name: link.contract };
+            const consumerRef = consumerSymbol || { filePath: '', name: link.contract };
+            // When the resolver finds a real graph symbol we keep its uid, otherwise
+            // fall back to the deterministic synthetic uid (see manifestSymbolUid).
+            const providerUid = providerSymbol?.uid || manifestSymbolUid(providerRepo, contractId);
+            const consumerUid = consumerSymbol?.uid || manifestSymbolUid(consumerRepo, contractId);
+            contracts.push({
+                contractId,
+                type: link.type,
+                role: 'provider',
+                symbolUid: providerUid,
+                symbolRef: providerRef,
+                symbolName: link.contract,
+                confidence: 1.0,
+                meta: { source: 'manifest' },
+                repo: providerRepo,
+            });
+            contracts.push({
+                contractId,
+                type: link.type,
+                role: 'consumer',
+                symbolUid: consumerUid,
+                symbolRef: consumerRef,
+                symbolName: link.contract,
+                confidence: 1.0,
+                meta: { source: 'manifest' },
+                repo: consumerRepo,
+            });
+            crossLinks.push({
+                from: { repo: consumerRepo, symbolUid: consumerUid, symbolRef: consumerRef },
+                to: { repo: providerRepo, symbolUid: providerUid, symbolRef: providerRef },
+                type: link.type,
+                contractId,
+                matchType: 'manifest',
+                confidence: 1.0,
+            });
+        }
+        return { contracts, crossLinks };
+    }
+    async resolveSymbol(repoPathKey, link, dbExecutors) {
+        const executor = dbExecutors?.get(repoPathKey);
+        if (!executor)
+            return null;
+        // NOTE: All lookups use EXACT equality on the relevant name field and
+        // deterministic ORDER BY before LIMIT 1. Previous versions used CONTAINS
+        // for fuzzy matching (plus an unconditional ".proto" fallback for gRPC)
+        // which produced silent false positives: e.g. manifest "/orders" would
+        // match "/suborders", and a gRPC manifest entry in a repo with any
+        // .proto file would attach to a random proto symbol.
+        //
+        // If resolveSymbol returns null, the extractor falls back to a
+        // deterministic synthetic uid via `manifestSymbolUid(repo, contractId)`
+        // (see the function's docstring for why synthetic rather than empty).
+        // Cross-impact still works: the bridge query joins on the synthetic
+        // uid, and the local impact engine derives the same uid for the
+        // unresolved symbol — name-based hints are the additional safety net.
+        try {
+            let rows;
+            if (link.type === 'http') {
+                // Route.name is the canonicalized URL path (see
+                // core/ingestion/pipeline.ts ensureSlash + generateId('Route', ...)).
+                // Normalize the manifest contract the same way so a user-written
+                // "/api/orders" matches "api/orders" in the graph.
+                //
+                // The contract may also use the explicit-method form "GET::/api/orders"
+                // recommended by buildContractId. Strip the METHOD:: prefix before
+                // normalizing — otherwise `normalizeRoutePath('GET::/api/orders')`
+                // returns `/GET::/api/orders` and never matches Route.name. The
+                // captured method is not yet used to constrain the Cypher query
+                // (method-aware HANDLES_ROUTE matching is a future enhancement).
+                const parsed = parseHttpContract(link.contract);
+                const normalized = normalizeRoutePath(parsed.path);
+                rows = await executor(`MATCH (handler)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)
+           WHERE route.name = $normalized
+           RETURN handler.id AS uid, handler.name AS name, handler.filePath AS filePath
+           ORDER BY handler.filePath ASC
+           LIMIT 1`, { normalized });
+            }
+            else if (link.type === 'topic') {
+                // Topic names aren't a first-class NodeLabel in the graph —
+                // topics are referenced by function/method symbols (Kafka
+                // listeners, publishers). Restrict to symbol-like labels to
+                // avoid cross-matching Files/Variables/Imports that happen to
+                // share the topic name.
+                rows = await executor(`MATCH (n:Function|Method|Class|Interface) WHERE n.name = $contract
+           RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
+           ORDER BY n.filePath ASC
+           LIMIT 1`, { contract: link.contract });
+            }
+            else if (link.type === 'grpc') {
+                // Contract is "Service/Method" or just "Service" (or package.Service
+                // variants). Prefer matching by method name when present, otherwise
+                // by service name. NO .proto path fallback — that's guaranteed to
+                // return a wrong symbol in any repo with more than one proto file.
+                // Label filters scope lookups: methods → Function|Method, services
+                // → Class|Interface (no label match = no silent wrong hits on
+                // File/Variable nodes that happen to share the name).
+                const parts = link.contract.split('/');
+                const serviceName = parts[0]?.trim() ?? '';
+                const methodName = parts[1]?.trim() ?? '';
+                if (methodName) {
+                    rows = await executor(`MATCH (n:Function|Method) WHERE n.name = $methodName
+             RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
+             ORDER BY n.filePath ASC
+             LIMIT 1`, { methodName });
+                }
+                else if (serviceName) {
+                    rows = await executor(`MATCH (n:Class|Interface) WHERE n.name = $serviceName
+             RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
+             ORDER BY n.filePath ASC
+             LIMIT 1`, { serviceName });
+                }
+                else {
+                    rows = [];
+                }
+            }
+            else if (link.type === 'lib') {
+                // Only exact match on the symbol's name. Previous fallback to
+                // CONTAINS on n.filePath would promote "react" to "react-native"
+                // or "@types/react" — silent wrong attribution. Restrict to
+                // package-level labels so we don't return arbitrary symbols
+                // named after a library.
+                rows = await executor(`MATCH (n:Package|Module) WHERE n.name = $contract
+           RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
+           ORDER BY n.filePath ASC
+           LIMIT 1`, { contract: link.contract });
+            }
+            else {
+                return null;
+            }
+            if (rows.length > 0) {
+                return {
+                    filePath: rows[0].filePath,
+                    name: rows[0].name,
+                    uid: String(rows[0].uid ?? ''),
+                };
+            }
+        }
+        catch (err) {
+            // Log but don't throw: a broken graph query in one repo shouldn't
+            // fail the whole manifest extraction. Unresolved contracts still
+            // get a synthetic symbolUid below, so cross-impact can proceed.
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[manifest-extractor] resolveSymbol failed for ${link.type}:${link.contract} ` +
+                `in ${repoPathKey}: ${message}`);
+        }
+        return null;
+    }
+    /**
+     * Build a canonical contract id for a manifest link.
+     *
+     * HTTP is the only type with two valid forms:
+     *   - Explicit method: `"GET::/api/orders"` → `"http::GET::/api/orders"`
+     *     (matches exactly against `HttpRouteExtractor` provider/consumer
+     *     contracts, which are also keyed by `http::<METHOD>::<path>`).
+     *   - Method-agnostic: `"/api/orders"` → `"http::*::/api/orders"`
+     *     — the `*` is a wildcard and is intended to match any concrete
+     *     HTTP method on that path. Wildcard-aware matching is the
+     *     responsibility of the sync / cross-impact layer (see #793);
+     *     downstream code should treat `http::*::<path>` as matching
+     *     every `http::<METHOD>::<path>` for the same path.
+     *
+     * Recommend the explicit-method form in group.yaml whenever the
+     * manifest author knows the method — it round-trips through exact
+     * equality matching without requiring wildcard logic downstream.
+     *
+     * NOTE on exhaustiveness: the switch covers every current
+     * `ContractType` variant and falls through to a `never` assertion so
+     * TypeScript fails the build if a new variant is added without a
+     * corresponding case.
+     */
+    buildContractId(type, contract) {
+        switch (type) {
+            case 'http': {
+                // Canonicalize method casing and path separators so logically
+                // equivalent inputs (`get::/api/orders` vs `GET::/api/orders`,
+                // or trailing-slash variants) produce the same contractId and
+                // matching `manifestSymbolUid` fallback. Without this, raw
+                // user casing leaks into cross-impact join keys and fragments
+                // matches across repos.
+                const { method, path: rawPath } = parseHttpContract(contract);
+                const normalizedPath = normalizeRoutePath(rawPath);
+                return method ? `http::${method}::${normalizedPath}` : `http::*::${normalizedPath}`;
+            }
+            case 'grpc':
+                return `grpc::${contract}`;
+            case 'topic':
+                return `topic::${contract}`;
+            case 'lib':
+                return `lib::${contract}`;
+            case 'custom':
+                return `custom::${contract}`;
+            default: {
+                const _exhaustive = type;
+                throw new Error(`Unhandled ContractType: ${String(_exhaustive)}`);
+            }
+        }
+    }
+}

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

@@ -4,6 +4,5 @@ export declare class TopicExtractor implements ContractExtractor {
     type: "topic";
     canExtract(_repo: RepoHandle): Promise<boolean>;
     extract(_dbExecutor: CypherExecutor | null, repoPath: string, _repo: RepoHandle): Promise<ExtractedContract[]>;
-    private scanFile;
     private dedupe;
 }

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

@@ -1,223 +1,86 @@
-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 makeContract(topicName, role, filePath, symbolName, confidence, broker) {
+import Parser from 'tree-sitter';
+import { readSafe } from './fs-utils.js';
+import { scanFile, unquoteLiteral } from './tree-sitter-scanner.js';
+import { TOPIC_SCAN_GLOB, getProviderForFile, } from './topic-patterns/index.js';
+/**
+ * Language-agnostic orchestrator for topic (message broker) contract
+ * extraction. All grammar-specific knowledge lives in `topic-patterns/*`
+ * — this file must not import any tree-sitter grammar directly.
+ *
+ * Flow per file:
+ *   1. `getProviderForFile(rel)` → compiled plugin (or `undefined` if the
+ *      file's extension isn't registered, in which case we skip it).
+ *   2. `scanFile(parser, provider, content)` → list of `{meta, valueText}`
+ *      pairs, one per matched literal.
+ *   3. `unquoteLiteral(valueText)` → the raw topic string.
+ *   4. `makeContract(topic, meta, relPath)` → `ExtractedContract`.
+ *
+ * Adding a new language is a one-file edit in `topic-patterns/index.ts`.
+ */
+function makeContract(topicName, meta, filePath) {
     return {
         contractId: `topic::${topicName}`,
         type: 'topic',
-        role,
+        role: meta.role,
         symbolUid: '',
-        symbolRef: { filePath: filePath.replace(/\\/g, '/'), name: symbolName },
-        symbolName,
-        confidence,
+        symbolRef: { filePath: filePath.replace(/\\/g, '/'), name: meta.symbolName },
+        symbolName: meta.symbolName,
+        confidence: meta.confidence,
         meta: {
-            broker,
+            broker: meta.broker,
             topicName,
-            extractionStrategy: 'source_scan',
+            extractionStrategy: 'tree_sitter',
         },
     };
 }
-// --- Kafka patterns ---
-const KAFKA_PATTERNS = [
-    // Java: @KafkaListener(topics = "xxx")
-    {
-        regex: /@KafkaListener\s*\(\s*topics\s*=\s*"([^"]+)"/g,
-        role: 'consumer',
-        broker: 'kafka',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'kafkaListener',
-    },
-    // Java: kafkaTemplate.send("xxx"
-    {
-        regex: /kafkaTemplate\.send\s*\(\s*"([^"]+)"/gi,
-        role: 'provider',
-        broker: 'kafka',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'kafkaTemplate.send',
-    },
-    // Node: producer.send({ topic: 'xxx'
-    {
-        regex: /producer\.send\s*\(\s*\{\s*topic:\s*['"]([^'"]+)['"]/g,
-        role: 'provider',
-        broker: 'kafka',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'producer.send',
-    },
-    // Node: consumer.subscribe({ topic: 'xxx'
-    {
-        regex: /consumer\.subscribe\s*\(\s*\{\s*topic:\s*['"]([^'"]+)['"]/g,
-        role: 'consumer',
-        broker: 'kafka',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'consumer.subscribe',
-    },
-    // Go: consumer.ConsumePartition("xxx"
-    {
-        regex: /\.ConsumePartition\s*\(\s*"([^"]+)"/g,
-        role: 'consumer',
-        broker: 'kafka',
-        confidence: 0.7,
-        topicGroup: 1,
-        symbolName: 'ConsumePartition',
-    },
-    // Python: KafkaConsumer('xxx'
-    {
-        regex: /KafkaConsumer\s*\(\s*['"]([^'"]+)['"]/g,
-        role: 'consumer',
-        broker: 'kafka',
-        confidence: 0.7,
-        topicGroup: 1,
-        symbolName: 'KafkaConsumer',
-    },
-    // Python: producer.send('xxx' or producer.produce('xxx'
-    {
-        regex: /producer\.(?:send|produce)\s*\(\s*['"]([^'"]+)['"]/g,
-        role: 'provider',
-        broker: 'kafka',
-        confidence: 0.7,
-        topicGroup: 1,
-        symbolName: 'producer.send',
-    },
-];
-// --- RabbitMQ patterns ---
-const RABBITMQ_PATTERNS = [
-    // Java: @RabbitListener(queues = "xxx")
-    {
-        regex: /@RabbitListener\s*\(\s*queues\s*=\s*"([^"]+)"/g,
-        role: 'consumer',
-        broker: 'rabbitmq',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'rabbitListener',
-    },
-    // Java: rabbitTemplate.convertAndSend("xxx"
-    {
-        regex: /rabbitTemplate\.convertAndSend\s*\(\s*"([^"]+)"/gi,
-        role: 'provider',
-        broker: 'rabbitmq',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'rabbitTemplate.convertAndSend',
-    },
-    // Node: channel.consume("xxx"
-    {
-        regex: /channel\.consume\s*\(\s*"([^"]+)"/g,
-        role: 'consumer',
-        broker: 'rabbitmq',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'channel.consume',
-    },
-    // Node: channel.publish("xxx"
-    {
-        regex: /channel\.publish\s*\(\s*"([^"]+)"/g,
-        role: 'provider',
-        broker: 'rabbitmq',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'channel.publish',
-    },
-    // Node: channel.sendToQueue("xxx"
-    {
-        regex: /channel\.sendToQueue\s*\(\s*"([^"]+)"/g,
-        role: 'provider',
-        broker: 'rabbitmq',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'channel.sendToQueue',
-    },
-    // Python: channel.basic_consume(queue='xxx'
-    {
-        regex: /channel\.basic_consume\s*\(\s*queue\s*=\s*['"]([^'"]+)['"]/g,
-        role: 'consumer',
-        broker: 'rabbitmq',
-        confidence: 0.7,
-        topicGroup: 1,
-        symbolName: 'basic_consume',
-    },
-    // Python: channel.basic_publish(exchange='xxx'
-    {
-        regex: /channel\.basic_publish\s*\([^)]*exchange\s*=\s*['"]([^'"]+)['"]/g,
-        role: 'provider',
-        broker: 'rabbitmq',
-        confidence: 0.7,
-        topicGroup: 1,
-        symbolName: 'basic_publish',
-    },
-];
-// --- NATS patterns ---
-const NATS_PATTERNS = [
-    // Go/Node: nc.Subscribe("xxx" or nc.subscribe("xxx"
-    {
-        regex: /nc\.(?:S|s)ubscribe\s*\(\s*"([^"]+)"/g,
-        role: 'consumer',
-        broker: 'nats',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'nc.Subscribe',
-    },
-    // Go/Node: nc.Publish("xxx" or nc.publish("xxx"
-    {
-        regex: /nc\.(?:P|p)ublish\s*\(\s*"([^"]+)"/g,
-        role: 'provider',
-        broker: 'nats',
-        confidence: 0.8,
-        topicGroup: 1,
-        symbolName: 'nc.Publish',
-    },
-];
-const ALL_PATTERNS = [...KAFKA_PATTERNS, ...RABBITMQ_PATTERNS, ...NATS_PATTERNS];
 export class TopicExtractor {
     type = 'topic';
     async canExtract(_repo) {
         return true;
     }
     async extract(_dbExecutor, repoPath, _repo) {
-        const files = await glob('**/*.{ts,tsx,js,jsx,java,go,py}', {
+        const files = await glob(TOPIC_SCAN_GLOB, {
             cwd: repoPath,
-            ignore: ['**/node_modules/**', '**/.git/**', '**/vendor/**', '**/dist/**', '**/build/**'],
+            ignore: [
+                '**/node_modules/**',
+                '**/.git/**',
+                '**/vendor/**',
+                '**/dist/**',
+                '**/build/**',
+                // Language-level test file conventions. Go test files
+                // `*_test.go` live next to source; other languages either use
+                // separate test directories (Python's `tests/`, Java's
+                // `src/test/`) or are already covered by the dist/build ignores.
+                // Pushed to the glob level so the orchestrator stays
+                // language-agnostic.
+                '**/*_test.go',
+            ],
             nodir: true,
         });
+        // One parser reused across files; the scanner calls `setLanguage` per
+        // file based on which plugin the registry returns.
+        const parser = new Parser();
         const out = [];
         for (const rel of files) {
+            const provider = getProviderForFile(rel);
+            if (!provider)
+                continue;
             const content = readSafe(repoPath, rel);
             if (!content)
                 continue;
-            out.push(...this.scanFile(content, rel));
-        }
-        return this.dedupe(out);
-    }
-    scanFile(content, filePath) {
-        const out = [];
-        for (const pattern of ALL_PATTERNS) {
-            // Reset regex state for each file
-            const re = new RegExp(pattern.regex.source, pattern.regex.flags);
-            let m;
-            while ((m = re.exec(content)) !== null) {
-                const topicName = m[pattern.topicGroup];
+            const matches = scanFile(parser, provider, content);
+            for (const match of matches) {
+                const valueNode = match.captures.value;
+                if (!valueNode)
+                    continue;
+                const topicName = unquoteLiteral(valueNode.text);
                 if (!topicName)
                     continue;
-                out.push(makeContract(topicName, pattern.role, filePath, pattern.symbolName, pattern.confidence, pattern.broker));
+                out.push(makeContract(topicName, match.meta, rel));
             }
         }
-        return out;
+        return this.dedupe(out);
     }
     dedupe(items) {
         const seen = new Set();

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

@@ -0,0 +1,2 @@
+import type { TopicMeta } from './types.js';
+export declare const GO_TOPIC_PROVIDER: import("../tree-sitter-scanner.js").CompiledPatterns<TopicMeta>;