gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/cli/tool.js

@@ -1,7 +1,7 @@
 /**
  * Direct CLI Tool Commands
  *
- * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Exposes GitNexus tools (query, context, impact, cypher, check) as direct CLI commands.
  * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
  *
  * Usage:
@@ -62,7 +62,8 @@ export async function queryCommand(queryText, options) {
     }
     const backend = await getBackend();
     const result = await backend.callTool('query', {
-        query: queryText,
+        // #2175: canonical param is search_query; the backend still accepts legacy "query".
+        search_query: queryText,
         task_context: options?.context,
         goal: options?.goal,
         limit: options?.limit ? parseInt(options.limit) : undefined,
@@ -119,12 +120,23 @@ export async function impactCommand(target, options) {
         const rawOffset = parseInt(options?.offset ?? '', 10);
         const parsedLimit = Number.isFinite(rawLimit) ? rawLimit : undefined;
         const parsedOffset = Number.isFinite(rawOffset) ? rawOffset : undefined;
+        // `--line` is a PDG-only statement anchor (1-based source line). Parse it to
+        // an integer when provided and thread it ONLY when present, so the backend's
+        // line-without-pdg / non-positive-integer validation fires on the real value
+        // rather than on a silently-dropped flag. A non-numeric `--line` parses to
+        // NaN, which the backend rejects as a non-positive integer (loud, not silent).
+        const parsedLine = options?.line !== undefined ? parseInt(options.line, 10) : undefined;
         const result = await backend.callTool('impact', {
             target: target || undefined,
             target_uid: options?.uid,
             file_path: options?.file,
             kind: options?.kind,
             direction: options?.direction || 'upstream',
+            // Forward the engine selector; backend validates the enum (callgraph/pdg)
+            // and treats the default 'callgraph' identically to an omitted mode.
+            mode: options?.mode,
+            // PDG-only statement anchor — forwarded only when --line was given.
+            ...(parsedLine !== undefined ? { line: parsedLine } : {}),
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,
             repo: options?.repo,
@@ -154,7 +166,8 @@ export async function cypherCommand(query, options) {
     }
     const backend = await getBackend();
     const result = await backend.callTool('cypher', {
-        query,
+        // #2175: canonical param is statement; the backend still accepts legacy "query".
+        statement: query,
         repo: options?.repo,
         branch: options?.branch,
     });
@@ -170,3 +183,83 @@ export async function detectChangesCommand(options) {
     });
     output(formatDetectChangesResult(result));
 }
+export async function checkCommand(options) {
+    if (!options?.cycles) {
+        process.stderr.write('Usage: gitnexus check --cycles [--json]\n');
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const backend = await getBackend();
+        const result = await backend.callTool('check', {
+            cycles: true,
+            repo: options.repo,
+            branch: options.branch,
+        });
+        if (result?.error) {
+            output(result);
+            process.exitCode = 1;
+            return;
+        }
+        if (options.json) {
+            output(result);
+        }
+        else if (result.cycleCount === 0) {
+            output('No circular imports found.');
+        }
+        else {
+            output(result.cycles.map((cycle) => cycle.files.join(' -> ')).join('\n'));
+        }
+        if (result.cycleCount > 0)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        output({ error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}
+export async function traceCommand(from, to, options) {
+    if (options?.fromUid?.startsWith('--') || options?.toUid?.startsWith('--')) {
+        cliErrorKey('tool.usage.trace');
+        process.exit(1);
+    }
+    if ((!from?.trim() && !options?.fromUid) || (!to?.trim() && !options?.toUid)) {
+        cliErrorKey('tool.usage.trace');
+        process.exit(1);
+    }
+    // Reject a non-numeric / non-positive --depth up front rather than forwarding
+    // NaN (which the backend would silently treat as the default).
+    if (options?.depth !== undefined) {
+        const parsedDepth = Number(options.depth);
+        if (!Number.isInteger(parsedDepth) || parsedDepth < 1) {
+            cliErrorKey('tool.usage.trace');
+            process.exit(1);
+        }
+    }
+    try {
+        const backend = await getBackend();
+        const result = await backend.callTool('trace', {
+            from: from || undefined,
+            from_uid: options?.fromUid,
+            from_file: options?.fromFile,
+            to: to || undefined,
+            to_uid: options?.toUid,
+            to_file: options?.toFile,
+            maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
+            includeTests: options?.includeTests ?? false,
+            repo: options?.repo,
+            branch: options?.branch,
+        });
+        output(result);
+    }
+    catch (err) {
+        output({
+            status: 'error',
+            error: (err instanceof Error ? err.message : String(err)) || 'Trace analysis failed unexpectedly',
+            from: { name: from },
+            to: { name: to },
+            suggestion: 'Try gitnexus context <symbol> to see connections, or check if an interface bridges them.',
+        });
+        process.exit(1);
+    }
+}

package/dist/core/embeddings/hf-env.d.ts

@@ -13,66 +13,6 @@ export declare const CB_RESET_TIMEOUT_MS = 60000;
 export declare const HF_MAX_TIMEOUT_MS: number;
 /** Upper bound clamped on the env-override attempt count. */
 export declare const HF_MAX_ATTEMPTS_CAP = 10;
-/**
- * @internal Exported only for unit tests and the two embedder entry points
- * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
- * public package API.
- *
- * Minimal subset of `@huggingface/transformers`' `env` object that gitnexus
- * mutates. Defining a local structural type keeps this helper free of a
- * transitive dependency on transformers' generated `.d.ts` while still
- * giving full type-checking on the two fields we actually touch.
- */
-export interface HfEnvSubset {
-    cacheDir: string;
-    remoteHost: string;
-}
-/**
- * @internal Exported only for unit tests and the two embedder entry points
- * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
- * public package API.
- *
- * Apply user-controlled HuggingFace environment overrides to the
- * `@huggingface/transformers` `env` object. Centralises the two env-var
- * bridges so every gitnexus embedder entry point (the analyze pipeline
- * and the MCP server) behaves identically.
- *
- * - **`HF_HOME`** → `env.cacheDir` (default: `~/.cache/huggingface`).
- *   transformers.js otherwise defaults to `./node_modules/.cache` inside
- *   its own install dir, which is unwritable when gitnexus is installed
- *   globally (e.g. `/usr/lib/node_modules/`).
- *
- * - **`HF_ENDPOINT`** → `env.remoteHost` (#1205). transformers.js does
- *   not read `HF_ENDPOINT` on its own — it reads `env.remoteHost` —
- *   even though `HF_ENDPOINT` is the standard env var the upstream
- *   `huggingface_hub` Python client and the official HF mirror docs
- *   tell users to set. Bridging the two unblocks `--embeddings` for
- *   users behind networks where `huggingface.co` is unreachable
- *   (corporate proxies, the GFW, air-gapped mirrors). The trailing
- *   slash is normalised because transformers.js builds URLs by string
- *   concatenation and a missing slash silently falls through to its
- *   default `huggingface.co/...` host.
- *
- * Mutation rather than return-and-apply because callers already hold a
- * reference to the live `env` object imported from
- * `@huggingface/transformers` — passing the same reference in keeps the
- * call site a single line at each entry point.
- */
-export declare function applyHfEnvOverrides(env: HfEnvSubset): void;
-/**
- * @internal Exported for unit tests and the two embedder entry points.
- *
- * Returns true when an error message indicates a network-level fetch failure
- * during HuggingFace model download (e.g. `TypeError: fetch failed`,
- * `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`).
- *
- * These errors are not device-specific and cannot be fixed by falling back to
- * a different ONNX device — the caller should rethrow immediately with
- * guidance about `HF_ENDPOINT`.
- */
-export declare function isNetworkFetchError(message: string): boolean;
-/** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
-export declare const CIRCUIT_OPEN_TAG = "hf-circuit-open";
 /**
  * Module-level singleton shared by both embedder entry points
  * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Per-process
@@ -82,18 +22,12 @@ export declare const CIRCUIT_OPEN_TAG = "hf-circuit-open";
  * recovery-time stampedes).
  */
 export declare const hfDownloadCircuit: CircuitBreaker;
-/** @internal Returns true for errors that should abort without retry (circuit-open). */
-export declare function isHfCircuitOpenError(message: string): boolean;
 /**
  * Returns true for any HuggingFace download failure that warrants showing the
  * `HF_ENDPOINT` remediation hint: either a raw network error or a
  * circuit-open rejection (which itself was caused by repeated network errors).
  */
 export declare function isHfDownloadFailure(message: string): boolean;
-/** @internal Wraps `fn` in a hard time-limit. The timeout error contains
- *  `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
- */
-export declare function withDownloadTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T>;
 export interface HfRetryOptions {
     /** Maximum total attempts including the initial one (default: `HF_MAX_ATTEMPTS`). */
     maxAttempts?: number;

package/dist/core/embeddings/http-client.d.ts

@@ -19,6 +19,13 @@ export declare const isHttpMode: () => boolean;
  * if HTTP mode is not active or no explicit dimensions are set.
  */
 export declare const getHttpDimensions: () => number | undefined;
+/**
+ * Return a safe representation of a URL for logs and error messages.
+ * Strips query string (may contain tokens) and userinfo (may contain
+ * credentials), keeping protocol + host + path. Exported so the CLI's
+ * custom-endpoint confirmation can mask the same way.
+ */
+export declare const safeUrl: (url: string) => string;
 /**
  * Embed texts via the HTTP backend, splitting into batches.
  * Reads config from env vars on every call.

package/dist/core/embeddings/http-client.js

@@ -56,10 +56,12 @@ export const isHttpMode = () => readConfig() !== null;
  */
 export const getHttpDimensions = () => readConfig()?.dimensions;
 /**
- * Return a safe representation of a URL for error messages.
- * Strips query string (may contain tokens) and userinfo.
+ * Return a safe representation of a URL for logs and error messages.
+ * Strips query string (may contain tokens) and userinfo (may contain
+ * credentials), keeping protocol + host + path. Exported so the CLI's
+ * custom-endpoint confirmation can mask the same way.
  */
-const safeUrl = (url) => {
+export const safeUrl = (url) => {
     try {
         const u = new URL(url);
         return `${u.protocol}//${u.host}${u.pathname}`;

package/dist/core/embeddings/server-mapping.d.ts

@@ -1,7 +1,7 @@
 /**
  * Server Mapping Configuration
  *
- * Reads ~/.gitnexus/server-mapping.json to map repo names to service names.
+ * Reads getGlobalDir()/server-mapping.json to map repo names to service names.
  * Used in embedding text to enrich metadata with microservice context.
  */
 /**

package/dist/core/embeddings/server-mapping.js

@@ -1,13 +1,17 @@
 /**
  * Server Mapping Configuration
  *
- * Reads ~/.gitnexus/server-mapping.json to map repo names to service names.
+ * Reads getGlobalDir()/server-mapping.json to map repo names to service names.
  * Used in embedding text to enrich metadata with microservice context.
  */
 import fs from 'fs/promises';
 import path from 'path';
-import os from 'os';
-const MAPPING_FILE = path.join(os.homedir(), '.gitnexus', 'server-mapping.json');
+import { getGlobalDir } from '../../storage/repo-manager.js';
+// Sourced from getGlobalDir() so it honors GITNEXUS_HOME (the Docker image sets
+// GITNEXUS_HOME=/data/gitnexus); falls back to ~/.gitnexus when unset. Wrapped in
+// path.resolve() for parity with the clone/upload roots (git-clone.ts CLONE_ROOT,
+// upload-paths.ts UPLOAD_ROOT) so a relative GITNEXUS_HOME still yields an absolute path.
+const MAPPING_FILE = path.resolve(path.join(getGlobalDir(), 'server-mapping.json'));
 let cachedMapping = null;
 /**
  * Read the server mapping file and return the serverName for a given repoName.

package/dist/core/graph/import-cycles.d.ts

@@ -0,0 +1,10 @@
+interface ImportEdge {
+    source: string;
+    target: string;
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export declare function findImportCycles(edges: ImportEdge[]): string[][];
+export {};

package/dist/core/graph/import-cycles.js

@@ -0,0 +1,103 @@
+function findCyclePath(component, adjacency) {
+    const allowed = new Set(component);
+    const start = component[0];
+    const parents = new Map([[start, null]]);
+    const queue = [start];
+    for (let index = 0; index < queue.length; index += 1) {
+        const node = queue[index];
+        for (const next of adjacency.get(node) ?? []) {
+            if (!allowed.has(next))
+                continue;
+            if (next === start) {
+                const path = [];
+                let cursor = node;
+                while (cursor !== null) {
+                    path.push(cursor);
+                    cursor = parents.get(cursor) ?? null;
+                }
+                path.reverse();
+                return [...path, start];
+            }
+            if (parents.has(next))
+                continue;
+            parents.set(next, node);
+            queue.push(next);
+        }
+    }
+    throw new Error('Invariant violation: no cycle found through SCC root.');
+}
+/**
+ * Return one deterministic concrete cycle for every cyclic strongly connected
+ * component in the file import graph.
+ */
+export function findImportCycles(edges) {
+    const adjacency = new Map();
+    for (const { source, target } of edges) {
+        if (!source || !target)
+            continue;
+        const targets = adjacency.get(source) ?? new Set();
+        targets.add(target);
+        adjacency.set(source, targets);
+        if (!adjacency.has(target))
+            adjacency.set(target, new Set());
+    }
+    const sortedAdjacency = new Map([...adjacency].map(([node, targets]) => [node, [...targets].sort()]));
+    const reverseAdjacency = new Map();
+    for (const node of sortedAdjacency.keys())
+        reverseAdjacency.set(node, []);
+    for (const [source, targets] of sortedAdjacency) {
+        for (const target of targets)
+            reverseAdjacency.get(target).push(source);
+    }
+    for (const sources of reverseAdjacency.values())
+        sources.sort();
+    const visited = new Set();
+    const finishOrder = [];
+    const components = [];
+    for (const start of [...sortedAdjacency.keys()].sort()) {
+        if (visited.has(start))
+            continue;
+        visited.add(start);
+        const stack = [{ node: start, nextIndex: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = sortedAdjacency.get(frame.node) ?? [];
+            if (frame.nextIndex < neighbors.length) {
+                const next = neighbors[frame.nextIndex++];
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    stack.push({ node: next, nextIndex: 0 });
+                }
+            }
+            else {
+                finishOrder.push(frame.node);
+                stack.pop();
+            }
+        }
+    }
+    visited.clear();
+    for (let index = finishOrder.length - 1; index >= 0; index -= 1) {
+        const start = finishOrder[index];
+        if (visited.has(start))
+            continue;
+        const component = [];
+        const stack = [start];
+        visited.add(start);
+        while (stack.length > 0) {
+            const node = stack.pop();
+            component.push(node);
+            for (const next of reverseAdjacency.get(node) ?? []) {
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                stack.push(next);
+            }
+        }
+        component.sort();
+        components.push(component);
+    }
+    return components
+        .filter((component) => component.length > 1 || (sortedAdjacency.get(component[0]) ?? []).includes(component[0]))
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map((component) => findCyclePath(component, sortedAdjacency));
+}

package/dist/core/group/cross-impact.d.ts

@@ -2,7 +2,7 @@
  * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
  * All bridge Cypher for this feature lives in this module.
  */
-import type { GroupImpactResult } from './types.js';
+import type { CrossRepoImpact, GroupImpactResult } from './types.js';
 import type { GroupToolPort } from './service.js';
 /** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
 export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
@@ -79,6 +79,7 @@ export declare function collectImpactSymbolUids(local: unknown, servicePrefix: s
     uids: string[];
     targetFilePath?: string;
 };
+export declare function mergeRisk(localRisk: string, cross: CrossRepoImpact[]): string;
 export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<string, unknown>): Promise<GroupImpactResult | {
     error: string;
 }>;

package/dist/core/group/cross-impact.js

@@ -251,7 +251,11 @@ function extractProcessNames(impact) {
         return [];
     return o.affected_processes.map((p) => String(p.name ?? '')).filter(Boolean);
 }
-function mergeRisk(localRisk, cross) {
+// Exported so the U4 PDG-result interchangeability contract (KTD8) can assert
+// permanently that a PDG `risk:'UNKNOWN'` never coalesces to a confident `LOW`.
+// No behavior change — `'UNKNOWN'` was already handled correctly at the
+// `(localRisk === 'LOW' || localRisk === 'UNKNOWN')` branch below.
+export function mergeRisk(localRisk, cross) {
     const highConf = cross.some((c) => c.contract.confidence >= 0.85);
     if (localRisk === 'CRITICAL')
         return 'CRITICAL';

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

@@ -1,23 +1,27 @@
 import { createRequire } from 'node:module';
+import { requireVendoredGrammar } from '../../../tree-sitter/vendored-grammars.js';
 import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js';
 /**
  * Protobuf (.proto) tree-sitter plugin for gRPC contract extraction.
  *
- * Uses `tree-sitter-proto` (coder3101/tree-sitter-proto) as an
- * optionalDependency — if the grammar is not installed (e.g. native
- * compilation failed on an unusual platform), the plugin exports
- * `null` and the orchestrator falls back to the existing manual
- * string-sanitizing parser.
+ * Uses `tree-sitter-proto` (coder3101/tree-sitter-proto), loaded from
+ * `vendor/` by absolute path (NEVER copied into node_modules — see
+ * vendored-grammars.ts / #2111). If the grammar's binding cannot be loaded
+ * (e.g. no prebuild for an unusual platform), the plugin exports `null` and the
+ * orchestrator falls back to the existing manual string-sanitizing parser.
  *
  * The grammar is vendored in `vendor/tree-sitter-proto/` with
  * parser.c regenerated against tree-sitter-cli 0.24 (ABI version 14)
  * so it is compatible with the project's tree-sitter 0.21.1 runtime
  * (which loads ABI 13–14).
  */
+// Only for `tree-sitter` (a real npm dependency) in the smoke-test below;
+// the vendored grammar goes through requireVendoredGrammar (never a bare
+// `_require('tree-sitter-proto')`, which would force a node_modules copy — #2111).
 const _require = createRequire(import.meta.url);
 let ProtoGrammar = null;
 try {
-    ProtoGrammar = _require('tree-sitter-proto');
+    ProtoGrammar = requireVendoredGrammar('tree-sitter-proto');
 }
 catch {
     // Grammar not installed — PROTO_GRPC_PLUGIN will be null.

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

@@ -1,4 +1,4 @@
-import { createRequire } from 'node:module';
+import { requireVendoredGrammar } from '../../../tree-sitter/vendored-grammars.js';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 /**
  * Kotlin HTTP plugin (Spring providers + consumers).
@@ -52,15 +52,15 @@ import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-s
  *         value_argument
  *           string_literal                ← the path
  *
- * tree-sitter-kotlin is an optional npm dependency — when its native
- * binding is unavailable the plugin gracefully exports `null` and
- * `http-patterns/index.ts` skips registration for `.kt`/`.kts` files.
+ * tree-sitter-kotlin is a vendored grammar loaded from `vendor/` by absolute
+ * path (NEVER copied into node_modules — see vendored-grammars.ts / #2111) —
+ * when its native binding is unavailable the plugin gracefully exports `null`
+ * and `http-patterns/index.ts` skips registration for `.kt`/`.kts` files.
  */
-const _require = createRequire(import.meta.url);
-/** Loaded lazily; null when the grammar binding isn't installed. */
+/** Loaded lazily; null when the grammar binding isn't available. */
 let Kotlin = null;
 try {
-    Kotlin = _require('tree-sitter-kotlin');
+    Kotlin = requireVendoredGrammar('tree-sitter-kotlin');
 }
 catch {
     Kotlin = null;

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

@@ -1,5 +1,29 @@
 import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
 import type { ExtractedContract, RepoHandle } from '../types.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 supplement (Strategy B)** — parse files directly with
+ *    the per-language plugin registry in `./http-patterns/`. Used to
+ *    fill gaps when graph extraction only covers part of a polyglot repo
+ *    (e.g. Java graph routes plus Go source-scan routes). Graph entries
+ *    remain authoritative for duplicate contract IDs because they carry
+ *    richer symbol metadata. 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.
+ */
+export declare const HANDLES_ROUTE_QUERY = "\nMATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)\nRETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,\n       route.name AS routePath, route.id AS routeId,\n       route.method AS routeMethod,\n       route.responseKeys AS responseKeys,\n       r.reason AS routeSource";
 /**
  * Canonicalize a provider-side HTTP path for contract-id generation:
  *   - strip query string

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

@@ -4,6 +4,7 @@ import Parser from 'tree-sitter';
 import { createIgnoreFilter } from '../../../config/ignore-service.js';
 import { readSafe } from './fs-utils.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
+import { logger } from '../../logger.js';
 import { getPluginForFile, HTTP_SCAN_GLOB, } from './http-patterns/index.js';
 /**
  * Language-agnostic orchestrator for HTTP route (provider + consumer)
@@ -29,10 +30,14 @@ import { getPluginForFile, HTTP_SCAN_GLOB, } from './http-patterns/index.js';
  * widen `HTTP_SCAN_GLOB` if needed.
  */
 // ─── Graph-assisted queries ──────────────────────────────────────────
-const HANDLES_ROUTE_QUERY = `
+// Exported so integration tests can run the exact production query against a
+// real LadybugDB (guards the Route.method column contract — see
+// route-method-roundtrip.test.ts).
+export const HANDLES_ROUTE_QUERY = `
 MATCH (handlerFile:File)-[r:CodeRelation {type: 'HANDLES_ROUTE'}]->(route:Route)
 RETURN handlerFile.id AS fileId, handlerFile.filePath AS filePath,
        route.name AS routePath, route.id AS routeId,
+       route.method AS routeMethod,
        route.responseKeys AS responseKeys,
        r.reason AS routeSource`;
 const FETCHES_QUERY = `
@@ -273,14 +278,26 @@ export class HttpRouteExtractor {
         try {
             rows = await db(HANDLES_ROUTE_QUERY);
         }
-        catch {
+        catch (err) {
+            // A failure here silently disables the entire graph-assisted HTTP
+            // provider path (the source-scan fallback still runs and masks most
+            // of the damage), so surface it at debug level to make a total
+            // outage observable instead of invisible.
+            logger.debug(`[http-route-extractor] HANDLES_ROUTE query failed; graph providers skipped: ${err instanceof Error ? err.message : String(err)}`);
             return [];
         }
         for (const row of rows) {
             const filePath = String(row.filePath ?? '');
             const routePath = String(row.routePath ?? '');
             const routeSource = String(row.routeSource ?? row.routeReason ?? '');
-            let method = methodFromRouteReason(routeSource);
+            // Prefer the HTTP verb persisted on the Route node by the ingestion
+            // routes phase (Spring/Laravel framework routes and decorator routes
+            // carry it). Fall back to parsing it out of the edge reason for
+            // older indexes or filesystem routes that never stored a method.
+            const graphMethod = String(row.routeMethod ?? '')
+                .trim()
+                .toUpperCase();
+            let method = (graphMethod || null) ?? methodFromRouteReason(routeSource);
             // 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`
@@ -396,7 +413,8 @@ export class HttpRouteExtractor {
         try {
             rows = await db(FETCHES_QUERY);
         }
-        catch {
+        catch (err) {
+            logger.debug(`[http-route-extractor] FETCHES query failed; graph consumers skipped: ${err instanceof Error ? err.message : String(err)}`);
             return [];
         }
         for (const row of rows) {