gitnexus 1.6.0 → 1.6.1

package/dist/core/group/extractors/http-route-extractor.js

@@ -1,6 +1,30 @@
-import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { glob } from 'glob';
+import Parser from 'tree-sitter';
+import { readSafe } from './fs-utils.js';
+import { getPluginForFile, HTTP_SCAN_GLOB } from './http-patterns/index.js';
+/**
+ * Language-agnostic orchestrator for HTTP route (provider + consumer)
+ * contract extraction. Two strategies, in order of preference per role:
+ *
+ * 1. **Graph-assisted (Strategy A)** — if a per-repo LadybugDB executor
+ *    is available, read `HANDLES_ROUTE` / `FETCHES` Cypher edges that
+ *    the ingestion pipeline already produced via tree-sitter. This is
+ *    the preferred path because the graph has richer symbol metadata
+ *    (real uids, class/method structure, etc.).
+ *
+ * 2. **Source-scan fallback (Strategy B)** — parse files directly with
+ *    the per-language plugin registry in `./http-patterns/`. Used when
+ *    the graph has no routes/fetches for this repo (e.g. a repo that
+ *    hasn't been indexed yet, or whose indexer doesn't know the
+ *    framework). Each plugin owns its tree-sitter grammar and query
+ *    sources — this orchestrator imports NO grammars or query strings.
+ *
+ * Adding a new language for Strategy B is a one-file edit in
+ * `http-patterns/index.ts`: register a new `HttpLanguagePlugin` and
+ * widen `HTTP_SCAN_GLOB` if needed.
+ */
+// ─── Graph-assisted queries ──────────────────────────────────────────
 const HANDLES_ROUTE_QUERY = `
 MATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)
 RETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,
@@ -17,13 +41,52 @@ MATCH (file:File {id: $fileId})<-[:CodeRelation {type: 'CONTAINS'}]-(sym)
 WHERE sym.startLine IS NOT NULL
 RETURN sym.id AS uid, sym.name AS name, sym.filePath AS filePath, labels(sym) AS labels
 ORDER BY sym.startLine`;
+// ─── Path normalization (shared between provider / consumer paths) ──
+/**
+ * Canonicalize a provider-side HTTP path for contract-id generation:
+ *   - strip query string
+ *   - lower-case
+ *   - drop trailing slash
+ *   - collapse `:id`, `{id}`, `[id]` path params into a single `{param}`
+ */
 export function normalizeHttpPath(p) {
     let s = p.trim().split('?')[0].toLowerCase().replace(/\/+$/, '');
     s = s.replace(/:\w+/g, '{param}');
     s = s.replace(/\{[^}]+\}/g, '{param}');
     s = s.replace(/\[[^\]]+\]/g, '{param}');
-    return s;
+    // Preserve root: after stripping trailing slashes, the root "/"
+    // collapses to "" which would produce malformed contract ids like
+    // `http::GET::`. Restore a single slash for the root case.
+    return s === '' ? '/' : s;
 }
+/**
+ * Consumer-side normalization is more aggressive:
+ *   - template literals (`${x}`) → `{param}`
+ *   - strip protocol + host if the URL is absolute
+ *   - numeric segments → `{param}` (so `/api/orders/42` → `/api/orders/{param}`)
+ */
+function normalizeConsumerPath(url) {
+    const templated = url.replace(/\$\{[^}]+\}/g, '{param}').trim();
+    let pathOnly = templated;
+    if (/^https?:\/\//i.test(templated)) {
+        try {
+            pathOnly = new URL(templated).pathname;
+        }
+        catch {
+            pathOnly = templated.replace(/^https?:\/\/[^/]+/i, '');
+        }
+    }
+    const normalized = normalizeHttpPath(pathOnly || '/');
+    const segments = normalized
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => (/^\d+$/.test(segment) ? '{param}' : segment));
+    return `/${segments.join('/')}`.replace(/\/+$/, '') || '/';
+}
+function contractIdFor(method, pathNorm) {
+    return `http::${method.toUpperCase()}::${pathNorm}`;
+}
+// ─── Graph row helpers ───────────────────────────────────────────────
 function methodFromRouteReason(reason) {
     const r = reason || '';
     if (/GetMapping|decorator-Get/i.test(r))
@@ -38,47 +101,6 @@ function methodFromRouteReason(reason) {
         return 'PATCH';
     return null;
 }
-function contractIdFor(method, pathNorm) {
-    return `http::${method.toUpperCase()}::${pathNorm}`;
-}
-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 pickJavaHandlerName(content, routePath, httpMethod) {
-    const tail = routePath.split('/').filter(Boolean).pop() || '';
-    const mapNames = {
-        GET: 'GetMapping',
-        POST: 'PostMapping',
-        PUT: 'PutMapping',
-        DELETE: 'DeleteMapping',
-        PATCH: 'PatchMapping',
-    };
-    const ann = mapNames[httpMethod] || 'GetMapping';
-    const lines = content.split(/\r?\n/);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (!line.includes(`@${ann}`))
-            continue;
-        if (!line.includes(`"${tail}"`) && !line.includes(`'${tail}'`) && tail && !line.includes(tail))
-            continue;
-        for (let j = i + 1; j < Math.min(i + 8, lines.length); j++) {
-            const m = lines[j].match(/(?:public|protected|private)\s+[\w<>,\s\[\]]+\s+(\w+)\s*\(/);
-            if (m)
-                return m[1];
-        }
-    }
-    return null;
-}
 function pickSymbolUid(rows, preferredName) {
     const norm = (x) => String(x ?? '');
     const labeled = rows.filter((r) => {
@@ -104,19 +126,71 @@ function pickSymbolUid(rows, preferredName) {
         filePath: norm(first?.filePath ?? first?.[2]),
     };
 }
+// ─── Orchestrator ────────────────────────────────────────────────────
 export class HttpRouteExtractor {
     type = 'http';
     async canExtract(_repo) {
         return true;
     }
-    async extract(dbExecutor, repoPath, repo) {
-        const graphP = dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, repoPath) : [];
-        const providers = graphP.length > 0 ? graphP : await this.extractProvidersSourceScan(repoPath);
-        const graphC = dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, repoPath) : [];
-        const consumers = graphC.length > 0 ? graphC : await this.extractConsumersSourceScan(repoPath);
+    async extract(dbExecutor, repoPath, _repo) {
+        // Parse each file at most once and reuse the plugin results across
+        // both graph-assisted enrichment and source-scan emission.
+        const parser = new Parser();
+        const cachedDetections = new Map();
+        const getDetections = (rel) => {
+            const cached = cachedDetections.get(rel);
+            if (cached)
+                return cached;
+            const plugin = getPluginForFile(rel);
+            if (!plugin) {
+                cachedDetections.set(rel, []);
+                return [];
+            }
+            const content = readSafe(repoPath, rel);
+            if (!content) {
+                cachedDetections.set(rel, []);
+                return [];
+            }
+            try {
+                parser.setLanguage(plugin.language);
+                const tree = parser.parse(content);
+                const detections = plugin.scan(tree);
+                cachedDetections.set(rel, detections);
+                return detections;
+            }
+            catch {
+                cachedDetections.set(rel, []);
+                return [];
+            }
+        };
+        // Glob the source-scan file list at most once per extract() —
+        // both provider and consumer fallback paths share the same list.
+        let scannedFiles = null;
+        const getScannedFiles = async () => {
+            if (scannedFiles)
+                return scannedFiles;
+            scannedFiles = await this.scanFiles(repoPath);
+            return scannedFiles;
+        };
+        const graphProviders = dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, getDetections) : [];
+        const providers = graphProviders.length > 0
+            ? graphProviders
+            : this.extractProvidersSourceScan(await getScannedFiles(), getDetections);
+        const graphConsumers = dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, getDetections) : [];
+        const consumers = graphConsumers.length > 0
+            ? graphConsumers
+            : this.extractConsumersSourceScan(await getScannedFiles(), getDetections);
         return [...providers, ...consumers];
     }
-    async extractProvidersGraph(db, repoPath) {
+    async scanFiles(repoPath) {
+        return glob(HTTP_SCAN_GLOB, {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/vendor/**'],
+            nodir: true,
+        });
+    }
+    // ─── Graph-assisted providers ──────────────────────────────────────
+    async extractProvidersGraph(db, getDetections) {
         const out = [];
         let rows;
         try {
@@ -130,15 +204,26 @@ export class HttpRouteExtractor {
             const routePath = String(row.routePath ?? '');
             const routeSource = String(row.routeSource ?? row.routeReason ?? '');
             let method = methodFromRouteReason(routeSource);
-            const content = readSafe(repoPath, filePath);
-            if (!method && content) {
-                method = this.inferMethodFromFileScan(content, routePath, 'provider');
+            // Look up handler name (and backfill method if missing) from the
+            // plugin's scan of the handler file. This replaces the old
+            // regex-based `inferMethodFromFileScan` and `pickJavaHandlerName`
+            // helpers — tree-sitter gives both pieces of information
+            // structurally. Always run the lookup: even when method is set by
+            // `methodFromRouteReason`, we still need the handler name.
+            const detections = filePath ? getDetections(filePath) : [];
+            const providerDetections = detections.filter((d) => d.role === 'provider');
+            let handlerName = null;
+            const normalizedRoute = normalizeHttpPath(routePath);
+            const match = providerDetections.find((d) => normalizeHttpPath(d.path) === normalizedRoute);
+            if (match) {
+                if (!method)
+                    method = match.method;
+                handlerName = match.name;
             }
             if (!method)
                 method = 'GET';
             const pathNorm = normalizeHttpPath(routePath);
             const cid = contractIdFor(method, pathNorm);
-            const handlerName = content && routePath ? pickJavaHandlerName(content, routePath, method) : null;
             let symbolUid = '';
             let symbolName = path.basename(filePath) || 'handler';
             let symPath = filePath;
@@ -176,134 +261,37 @@ export class HttpRouteExtractor {
         }
         return out;
     }
-    inferMethodFromFileScan(content, routePath, _role) {
-        const tail = routePath.split('/').filter(Boolean).pop() || '';
-        for (const m of ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']) {
-            const mapNames = {
-                GET: 'GetMapping',
-                POST: 'PostMapping',
-                PUT: 'PutMapping',
-                DELETE: 'DeleteMapping',
-                PATCH: 'PatchMapping',
-            };
-            if (content.includes(`@${mapNames[m]}`) &&
-                (content.includes(tail) || routePath.includes(tail))) {
-                return m;
-            }
-        }
-        return null;
-    }
-    async extractProvidersSourceScan(repoPath) {
-        const files = await glob('**/*.{ts,tsx,js,jsx,java,vue,svelte,php,py}', {
-            cwd: repoPath,
-            ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
-            nodir: true,
-        });
+    // ─── Source-scan providers ─────────────────────────────────────────
+    extractProvidersSourceScan(files, getDetections) {
         const out = [];
         for (const rel of files) {
-            const content = readSafe(repoPath, rel);
-            if (!content)
-                continue;
-            out.push(...this.scanSpringProviders(content, rel));
-            out.push(...this.scanExpressProviders(content, rel));
-            out.push(...this.scanLaravelProviders(content, rel));
-            out.push(...this.scanFastApiProviders(content, rel));
+            const detections = getDetections(rel);
+            for (const d of detections) {
+                if (d.role !== 'provider')
+                    continue;
+                const pathNorm = normalizeHttpPath(d.path);
+                out.push({
+                    contractId: contractIdFor(d.method, pathNorm),
+                    type: 'http',
+                    role: 'provider',
+                    symbolUid: '',
+                    symbolRef: { filePath: rel, name: d.name ?? 'handler' },
+                    symbolName: d.name ?? 'handler',
+                    confidence: d.confidence,
+                    meta: {
+                        method: d.method,
+                        path: pathNorm,
+                        pathSegments: pathNorm.split('/').filter(Boolean),
+                        extractionStrategy: 'source_scan',
+                        framework: d.framework,
+                    },
+                });
+            }
         }
         return this.dedupeContracts(out);
     }
-    dedupeContracts(items) {
-        const seen = new Set();
-        const out = [];
-        for (const c of items) {
-            const k = `${c.contractId}|${c.symbolRef.filePath}|${c.symbolRef.name}`;
-            if (seen.has(k))
-                continue;
-            seen.add(k);
-            out.push(c);
-        }
-        return out;
-    }
-    scanSpringProviders(content, filePath) {
-        const out = [];
-        // Skip Feign/client interfaces — annotated methods in interfaces are
-        // consumers (Feign, JAX-RS proxies), not provider endpoints.
-        // Anchored to line start (with optional access modifier) so we do not
-        // match "interface" inside comments or string literals.
-        if (/^\s*(?:public\s+)?interface\s+\w+/m.test(content) &&
-            !/@(?:Rest)?Controller\b/.test(content)) {
-            return out;
-        }
-        let classPrefix = '';
-        const classRm = content.match(/@RequestMapping\s*\(\s*"([^"]+)"/);
-        if (classRm)
-            classPrefix = classRm[1].replace(/\/+$/, '');
-        const re = /@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*"([^"]+)"/gi;
-        let m;
-        while ((m = re.exec(content)) !== null) {
-            const method = m[1].toUpperCase();
-            let p = m[2];
-            if (classPrefix)
-                p = `${classPrefix}/${p.replace(/^\//, '')}`;
-            const pathNorm = normalizeHttpPath(p);
-            const sub = content.slice(m.index);
-            const nameM = sub.match(/(?:public|protected|private)\s+[\w<>,\s\[\]]+\s+(\w+)\s*\(/);
-            const name = nameM ? nameM[1] : m[0];
-            out.push(this.makeProvider(filePath, method, pathNorm, name, 0.8));
-        }
-        return out;
-    }
-    scanExpressProviders(content, filePath) {
-        const out = [];
-        const re = /(?:router|app)\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/gi;
-        let m;
-        while ((m = re.exec(content)) !== null) {
-            const method = m[1].toUpperCase();
-            const pathNorm = normalizeHttpPath(m[2]);
-            out.push(this.makeProvider(filePath, method, pathNorm, 'handler', 0.8));
-        }
-        return out;
-    }
-    scanLaravelProviders(content, filePath) {
-        const out = [];
-        const re = /Route::(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/gi;
-        let m;
-        while ((m = re.exec(content)) !== null) {
-            const method = m[1].toUpperCase();
-            const pathNorm = normalizeHttpPath(m[2]);
-            out.push(this.makeProvider(filePath, method, pathNorm, 'route', 0.8));
-        }
-        return out;
-    }
-    scanFastApiProviders(content, filePath) {
-        const out = [];
-        const re = /@app\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/gi;
-        let m;
-        while ((m = re.exec(content)) !== null) {
-            const method = m[1].toUpperCase();
-            const pathNorm = normalizeHttpPath(m[2]);
-            out.push(this.makeProvider(filePath, method, pathNorm, 'handler', 0.8));
-        }
-        return out;
-    }
-    makeProvider(filePath, method, pathNorm, name, confidence) {
-        const cid = contractIdFor(method, pathNorm);
-        return {
-            contractId: cid,
-            type: 'http',
-            role: 'provider',
-            symbolUid: '',
-            symbolRef: { filePath, name },
-            symbolName: name,
-            confidence,
-            meta: {
-                method,
-                path: pathNorm,
-                pathSegments: pathNorm.split('/').filter(Boolean),
-                extractionStrategy: 'source_scan',
-            },
-        };
-    }
-    async extractConsumersGraph(db, repoPath) {
+    // ─── Graph-assisted consumers ──────────────────────────────────────
+    async extractConsumersGraph(db, getDetections) {
         const out = [];
         let rows;
         try {
@@ -317,12 +305,12 @@ export class HttpRouteExtractor {
             const routePath = String(row.routePath ?? '');
             const pathNorm = normalizeHttpPath(routePath);
             let method = 'GET';
-            const content = readSafe(repoPath, filePath);
-            if (content) {
-                const inferred = this.inferFetchMethod(content, pathNorm);
-                if (inferred)
-                    method = inferred;
-            }
+            // Prefer the plugin's detected method if we can find a matching
+            // fetch/axios call in the same file.
+            const detections = filePath ? getDetections(filePath) : [];
+            const inferred = detections.find((d) => d.role === 'consumer' && normalizeConsumerPath(d.path) === pathNorm);
+            if (inferred)
+                method = inferred.method;
             const cid = contractIdFor(method, pathNorm);
             let symbolUid = '';
             let symbolName = 'fetch';
@@ -360,69 +348,44 @@ export class HttpRouteExtractor {
         }
         return out;
     }
-    inferFetchMethod(content, pathNorm) {
-        const esc = pathNorm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        const fetchRe = new RegExp(`fetch\\s*\\(\\s*['"\`]([^'"\`]*${esc}[^'"\`]*)['"\`]\\s*,\\s*\\{[^}]*method:\\s*['"](\\w+)['"]`, 'i');
-        const m = content.match(fetchRe);
-        if (m)
-            return m[2].toUpperCase();
-        return null;
-    }
-    async extractConsumersSourceScan(repoPath) {
-        const files = await glob('**/*.{ts,tsx,js,jsx,vue,svelte}', {
-            cwd: repoPath,
-            ignore: ['**/node_modules/**', '**/.git/**'],
-            nodir: true,
-        });
+    // ─── Source-scan consumers ─────────────────────────────────────────
+    extractConsumersSourceScan(files, getDetections) {
         const out = [];
         for (const rel of files) {
-            const content = readSafe(repoPath, rel);
-            if (!content)
-                continue;
-            out.push(...this.scanFetchConsumers(content, rel));
-            out.push(...this.scanAxiosConsumers(content, rel));
+            const detections = getDetections(rel);
+            for (const d of detections) {
+                if (d.role !== 'consumer')
+                    continue;
+                const pathNorm = normalizeConsumerPath(d.path);
+                out.push({
+                    contractId: contractIdFor(d.method, pathNorm),
+                    type: 'http',
+                    role: 'consumer',
+                    symbolUid: '',
+                    symbolRef: { filePath: rel, name: 'fetch' },
+                    symbolName: 'fetch',
+                    confidence: d.confidence,
+                    meta: {
+                        method: d.method,
+                        path: pathNorm,
+                        extractionStrategy: 'source_scan',
+                        framework: d.framework,
+                    },
+                });
+            }
         }
         return this.dedupeContracts(out);
     }
-    scanFetchConsumers(content, filePath) {
-        const out = [];
-        const re = /fetch\s*\(\s*['"`]([^'"`]+)['"`](?:\s*,\s*\{[^}]*method:\s*['"](\w+)['"][^}]*\})?\s*\)/gi;
-        let m;
-        while ((m = re.exec(content)) !== null) {
-            const pathNorm = normalizeHttpPath(this.templateToPattern(m[1]));
-            const method = (m[2] || 'GET').toUpperCase();
-            out.push(this.makeConsumer(filePath, method, pathNorm, 0.7));
-        }
-        return out;
-    }
-    templateToPattern(url) {
-        return url.replace(/\$\{[^}]+\}/g, '{param}');
-    }
-    scanAxiosConsumers(content, filePath) {
+    dedupeContracts(items) {
+        const seen = new Set();
         const out = [];
-        const re = /axios\.(get|post|put|delete|patch)\s*\(\s*[`'"]([^`'"]+)[`'"]/gi;
-        let m;
-        while ((m = re.exec(content)) !== null) {
-            const method = m[1].toUpperCase();
-            const pathNorm = normalizeHttpPath(this.templateToPattern(m[2]));
-            out.push(this.makeConsumer(filePath, method, pathNorm, 0.7));
+        for (const c of items) {
+            const k = `${c.contractId}|${c.symbolRef.filePath}|${c.symbolRef.name}`;
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(c);
         }
         return out;
     }
-    makeConsumer(filePath, method, pathNorm, confidence) {
-        return {
-            contractId: contractIdFor(method, pathNorm),
-            type: 'http',
-            role: 'consumer',
-            symbolUid: '',
-            symbolRef: { filePath, name: 'fetch' },
-            symbolName: 'fetch',
-            confidence,
-            meta: {
-                method,
-                path: pathNorm,
-                extractionStrategy: 'source_scan',
-            },
-        };
-    }
 }

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

@@ -0,0 +1,54 @@
+import type { CrossLink, GroupManifestLink, StoredContract } from '../types.js';
+import type { CypherExecutor } from '../contract-extractor.js';
+export interface ManifestExtractResult {
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+}
+/**
+ * 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 declare function manifestSymbolUid(repo: string, contractId: string): string;
+export declare class ManifestExtractor {
+    extractFromManifest(links: GroupManifestLink[], dbExecutors?: Map<string, CypherExecutor>): Promise<ManifestExtractResult>;
+    private resolveSymbol;
+    /**
+     * 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.
+     */
+    private buildContractId;
+}