gitnexus 1.6.13-rc.74 → 1.6.13-rc.76

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

@@ -1,19 +1,30 @@
 import Go from 'tree-sitter-go';
-import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
+import { goImportPackageName } from '../../../ingestion/languages/go/import-package-name.js';
+import { stringLiteral } from '../../../ingestion/route-extractors/go-shared.js';
+import { compilePatterns, runCompiledPatterns, } from '../tree-sitter-scanner.js';
 /**
  * Go HTTP plugin. Handles:
- *   - gin / echo / chi framework routing — `r.GET("/path", handler)`
+ *   - gin / echo framework routing — `r.GET("/path", handler)`, including
+ *     prefixes from route groups bound in the same function (`r.Group("/api")`)
  *   - net/http stdlib — `http.HandleFunc("/path", handler)`
  *   - net/http consumer — `http.Get(...)`, `http.NewRequest("METHOD", ...)`
  *   - resty consumer — `client.R().Delete("/path")`
  */
 // ─── Provider: framework routing ──────────────────────────────────────
-// Matches `\w+\.GET(...)` etc. (gin, echo, chi all share this shape).
-// Captures the HTTP method (field name), path literal, and the handler —
-// anchored to the LAST argument (`@handler .`) so a variadic middleware
-// chain (`r.GET("/x", mw, handler)`, gin/echo/chi style) binds the real
-// handler, not a middleware identifier (which would otherwise over-match
-// and attach the route to the wrong symbol — see #2276 review).
+// Matches `\w+\.GET(...)` etc. (gin and echo share this shape).
+// Captures the receiver, the HTTP method (field name), and the path literal
+// (either Go string form; stringLiteral decodes both, as ingestion does). The
+// query does not anchor the path with `.`: tree-sitter counts comments as
+// named children, so `GET(/* c */ "/p", h)` would fail the anchor. scan instead
+// requires the path to be the first argument in code (comments skipped) and
+// picks the handler out of the remaining code arguments. Which argument that is depends on the framework:
+// gin is `GET(path, middleware..., handler)` (last), echo is
+// `GET(path, handler, middleware...)` (first) — see readFrameworkImports and
+// the per-call choice in scan below.
+// The handler must be an identifier, an inline func literal, or a method
+// value / package-qualified function (`h.ListUsers`, `handlers.ListUsers`);
+// anything else there means the call cannot be attributed to a symbol, so it
+// is dropped rather than guessed (variadic-middleware over-match, #2276).
 const FRAMEWORK_ROUTE_PATTERNS = compilePatterns({
     name: 'go-framework-route',
     language: Go,
@@ -23,15 +34,407 @@ const FRAMEWORK_ROUTE_PATTERNS = compilePatterns({
             query: `
         (call_expression
           function: (selector_expression
+            operand: (_) @receiver
             field: (field_identifier) @http_method (#match? @http_method "^(GET|POST|PUT|DELETE|PATCH)$"))
           arguments: (argument_list
-            (interpreted_string_literal) @path
-            [(identifier) (func_literal)] @handler
-            .))
+            [(interpreted_string_literal) (raw_string_literal)] @path))
       `,
         },
     ],
 });
+/** Named children that are code, not comments (tree-sitter names comments). */
+function codeChildren(node) {
+    return node ? node.namedChildren.filter((c) => c.type !== 'comment') : [];
+}
+/** Argument forms a route handler may take. */
+const HANDLER_ARG_TYPES = new Set([
+    'identifier',
+    'func_literal',
+    'selector_expression',
+]);
+/**
+ * The file's framework import aliases: which local qualifiers resolve to
+ * echo and to gin. Matched on the import path rather than the local name, so
+ * an aliased import still counts; an unaliased import is keyed by its
+ * conventional package name (`goImportPackageName`). `_` and `.` imports bind
+ * no qualifier this file can route through. An empty set means the file
+ * proves nothing about that framework. Echo's verb calls take the handler as
+ * the FIRST argument after the path (`GET(path, handler, middleware...)`),
+ * gin's as the LAST (`GET(path, middleware..., handler)`) — `scan` picks the
+ * rule per call from these sets.
+ */
+function readFrameworkImports(root) {
+    // Imports sit only at file scope; skip bodies.
+    const specs = root.namedChildren
+        .filter((node) => node.type === 'import_declaration')
+        .flatMap((decl) => decl.descendantsOfType('import_spec'));
+    const echo = new Set();
+    const gin = new Set();
+    for (const spec of specs) {
+        const importPath = stringLiteral(spec.childForFieldName('path'));
+        if (importPath === null)
+            continue;
+        const local = spec.childForFieldName('name')?.text ?? goImportPackageName(importPath);
+        if (local === '_' || local === '.')
+            continue;
+        if (importPath.includes('labstack/echo'))
+            echo.add(local);
+        else if (importPath.includes('gin-gonic/gin'))
+            gin.add(local);
+    }
+    return { echo, gin };
+}
+// ─── Route groups: `v1 := r.Group("/api/v1")` ─────────────────────────
+// gin (`*gin.RouterGroup`) and echo (`*echo.Group`) routes registered on a
+// group inherit every enclosing `Group(prefix)`. The prefix is recovered by
+// walking the route's receiver back through its bindings, lexically, inside
+// the enclosing function declaration only: a group handed to another
+// function (`registerAdmin(v1)`) arrives as a parameter and contributes no
+// prefix there, and a receiver bound to anything but a literal-prefix
+// `Group(...)` call contributes none either — the route keeps its literal path.
+// Statement-scoped bindings count too: an `if`/`switch` initializer, a `for`
+// clause (including `range`), a type-switch guard, and declarations inside a
+// switch case all scope over their statement the same way Go scopes them, so
+// they shadow an outer group of the same name instead of being skipped. A
+// select case's receive binding (`case g := <-ch:`) stops the walk entirely:
+// what arrives from the channel is statically unknown, so the route keeps its
+// literal path rather than inheriting an outer group.
+const MAX_GROUP_DEPTH = 32;
+function joinRoutePath(prefix, relative) {
+    let joined = relative;
+    if (prefix && relative) {
+        joined = `${prefix.replace(/\/+$/, '')}/${relative.replace(/^\/+/, '')}`;
+    }
+    else if (prefix) {
+        joined = prefix;
+    }
+    // Collapse duplicate slashes on the FINAL result — every return branch, not
+    // just the join — because ingestion's normalizeExtractedRoutePath collapses
+    // all "//" while the downstream contract-id normalizer does not: a path
+    // that keeps "//" would split into two contract ids across the strategies.
+    const collapsed = joined.replace(/\/+/g, '/');
+    // Force a leading "/" for the same reason: ingestion's
+    // normalizeExtractedRoutePath always adds one, while normalizeHttpPath (the
+    // shared contract-id normalizer) does not — a literal "x" or a slashless
+    // Group("api") prefix would emit `...::x` here and `...::/x` there. Gin
+    // also refuses a registration path that does not start with "/".
+    return collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
+}
+/** `parent.Group("/p", mw...)` → its receiver and literal prefix; null otherwise. */
+function asGroupCall(node) {
+    if (node.type !== 'call_expression')
+        return null;
+    const fn = node.childForFieldName('function');
+    if (fn?.type !== 'selector_expression' || fn.childForFieldName('field')?.text !== 'Group') {
+        return null;
+    }
+    const parent = fn.childForFieldName('operand');
+    const first = codeChildren(node.childForFieldName('arguments'))[0];
+    // Only a string literal carries a prefix, and it must decode to the text
+    // the runtime registers: stringLiteral applies Go unescaping (both `"…"`
+    // with escapes and raw `` `…` `` strings). A non-literal argument (a
+    // variable, concatenation) or an undecodable string contributes no prefix.
+    const prefix = first ? stringLiteral(first) : null;
+    if (!parent || prefix === null)
+        return null;
+    return { parent, prefix };
+}
+/** The expression `name` is assigned by `stmt` (`:=`, `=`, or `var`), if any. */
+function boundValue(stmt, name) {
+    const pick = (names, values) => {
+        const i = names.findIndex((n) => n.type === 'identifier' && n.text === name);
+        if (i < 0)
+            return undefined;
+        return codeChildren(values)[i] ?? null;
+    };
+    switch (stmt.type) {
+        case 'short_var_declaration':
+        case 'assignment_statement':
+            return pick(codeChildren(stmt.childForFieldName('left')), stmt.childForFieldName('right'));
+        case 'var_spec':
+            return pick(stmt.childrenForFieldName('name'), stmt.childForFieldName('value'));
+        case 'var_declaration': {
+            const specs = stmt.namedChildren.flatMap((c) => c.type === 'var_spec_list' ? c.namedChildren : [c]);
+            for (const spec of specs) {
+                if (spec.type !== 'var_spec')
+                    continue;
+                const value = pick(spec.childrenForFieldName('name'), spec.childForFieldName('value'));
+                if (value !== undefined)
+                    return value;
+            }
+            return undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * A binding whose value cannot be established statically: an earlier
+ * statement writes the name inside a nested scope (`{ g = r.Group("/new") }`,
+ * a branch or loop body), so which value reaches the use depends on control
+ * flow. Callers decline the route instead of picking the older binding.
+ */
+const CONFLICT = Symbol('conflicting-binding');
+function isParamBinding(b) {
+    return typeof b === 'object' && b !== null && 'param' in b;
+}
+/** The parameter_declaration of `fn` (parameters or method receiver) declaring `name`. */
+function paramDeclaring(fn, name) {
+    for (const list of [fn.childForFieldName('parameters'), fn.childForFieldName('receiver')]) {
+        for (const decl of codeChildren(list)) {
+            if (decl.type !== 'parameter_declaration' && decl.type !== 'variadic_parameter_declaration') {
+                continue;
+            }
+            if (decl.childrenForFieldName('name').some((n) => n.text === name))
+                return decl;
+        }
+    }
+    return null;
+}
+/** Whether `inner` lies within `outer`'s source span. */
+function within(outer, inner) {
+    return !!outer && outer.startIndex <= inner.startIndex && inner.endIndex <= outer.endIndex;
+}
+/**
+ * Whether `stmt` writes `name` with a plain assignment somewhere inside it
+ * (`g = …` in a nested block, branch, loop, or closure body). A nested `:=`
+ * declares a new variable and is not a write to the outer one.
+ */
+function writesNameInside(stmt, name) {
+    return [stmt, ...stmt.descendantsOfType('assignment_statement')].some((a) => a.type === 'assignment_statement' && declaresName(a.childForFieldName('left'), name));
+}
+/** Whether an identifier or expression_list (e.g. a range left side) declares `name`. */
+function declaresName(node, name) {
+    if (!node)
+        return false;
+    if (node.type === 'identifier')
+        return node.text === name;
+    return node.namedChildren.some((n) => n.type === 'identifier' && n.text === name);
+}
+/**
+ * The value last bound to identifier `ident` before its use: the nearest
+ * binding site in the enclosing scopes, walking outward — preceding statements
+ * in blocks and switch/select cases (`expression_case`/`type_case`/
+ * `communication_case`/`default_case` act as statement containers), then
+ * statement-scoped bindings (`if`/`switch` initializers, `for` clauses
+ * including `range`, type-switch guards), up to the enclosing function
+ * declaration. Returns null when the name is a parameter, is bound without a
+ * value, is received from a channel by a select case head (the received value
+ * is statically unknown, so the walk stops instead of escaping to an outer
+ * group), or is not bound in scope.
+ */
+function findBinding(ident) {
+    const binding = lookupBinding(ident);
+    return isParamBinding(binding) ? null : (binding ?? null);
+}
+/**
+ * findBinding's walk, keeping "declared without a traceable value" (null: a
+ * `func` literal parameter, `var x T`, a select receive) apart from "not
+ * declared before reaching the enclosing function declaration" (undefined).
+ * CONFLICT means a preceding statement writes the name in a nested scope, so
+ * the value at the use is control-flow dependent. A parameter or method
+ * receiver of the enclosing function returns its declaration (ParamBinding):
+ * no value, but a static type.
+ */
+function lookupBinding(ident) {
+    const name = ident.text;
+    let child = ident;
+    for (let node = ident.parent; node; child = node, node = node.parent) {
+        if (node.type === 'function_declaration' ||
+            node.type === 'method_declaration' ||
+            node.type === 'func_literal') {
+            const param = paramDeclaring(node, name);
+            if (param)
+                return { param };
+            if (node.type === 'func_literal')
+                continue;
+            return undefined;
+        }
+        // Inside a grouped `var ( a = …; b = a.Group(…) )`, the specs before the
+        // one holding the use are already in scope; the current and later specs
+        // are not (`var g = g.Group(…)` reads the outer g).
+        if (node.type === 'var_spec_list') {
+            const specs = codeChildren(node);
+            const useIndex = specs.findIndex((s) => s.id === child.id);
+            for (const spec of specs.slice(0, useIndex).reverse()) {
+                const value = boundValue(spec, name);
+                if (value !== undefined)
+                    return value;
+            }
+            continue;
+        }
+        if (node.type === 'block' ||
+            node.type === 'expression_case' ||
+            node.type === 'type_case' ||
+            node.type === 'communication_case' ||
+            node.type === 'default_case') {
+            // A select case head can rebind the name (`case g := <-ch:` or
+            // `case g = <-ch:`); the received value is statically unknown, so the
+            // walk must STOP with no traceable value — the same decline the
+            // ingestion-side route bindings record (value null) — instead of
+            // escaping to an outer group of the same name.
+            if (node.type === 'communication_case') {
+                for (const head of node.children) {
+                    if (head.type === 'receive_statement' &&
+                        declaresName(head.childForFieldName('left'), name)) {
+                        return null;
+                    }
+                }
+            }
+            const stmts = codeChildren(node);
+            const useIndex = stmts.findIndex((s) => s.id === child.id);
+            for (const stmt of stmts.slice(0, useIndex).reverse()) {
+                const value = boundValue(stmt, name);
+                if (value !== undefined)
+                    return value;
+                // A write nested in an earlier statement (block, branch, loop) may or
+                // may not run before the use: the reaching value is unprovable.
+                if (writesNameInside(stmt, name))
+                    return CONFLICT;
+            }
+            continue;
+        }
+        // Statement-scoped bindings enclose the use the same way Go scopes them.
+        if (node.type === 'if_statement' || node.type === 'expression_switch_statement') {
+            // A use inside the initializer itself (`if g := g.Group(…); …`) reads
+            // the OUTER binding: the new one only scopes over what follows it.
+            const init = node.childForFieldName('initializer');
+            if (init && !within(init, ident)) {
+                const value = boundValue(init, name);
+                if (value !== undefined)
+                    return value;
+            }
+            continue;
+        }
+        if (node.type === 'for_statement') {
+            const clause = codeChildren(node)[0];
+            // A write in the loop's post statement, condition, or body runs between
+            // iterations, so from the second pass on the body sees that value
+            // instead of the one it entered with (`for ; c; g = r.Group("/post")`):
+            // the prefix is control-flow dependent, so decline it.
+            if (within(node.childForFieldName('body'), ident)) {
+                const loopParts = [
+                    node.childForFieldName('body'),
+                    clause?.type === 'for_clause' ? clause.childForFieldName('update') : null,
+                    clause?.type === 'for_clause' ? clause.childForFieldName('condition') : null,
+                ];
+                if (loopParts.some((part) => part && writesNameInside(part, name)))
+                    return CONFLICT;
+            }
+            if (clause?.type === 'for_clause') {
+                // Only the initializer binds before the body; an absent initializer
+                // (`for ; c; i++`) binds nothing.
+                const init = clause.childForFieldName('initializer');
+                if (init && !within(init, ident)) {
+                    const value = boundValue(init, name);
+                    if (value !== undefined)
+                        return value;
+                }
+            }
+            else if (clause?.type === 'range_clause') {
+                if (declaresName(clause.childForFieldName('left'), name) &&
+                    !within(clause.childForFieldName('right'), ident)) {
+                    return clause.childForFieldName('right') ?? null;
+                }
+            }
+            continue;
+        }
+        if (node.type === 'type_switch_statement') {
+            // `switch g := x.(type)` — the guard list is the `alias` field, which
+            // only the `:=` form has (bare `switch x.(type)` parses with none),
+            // matching how the ingestion-side route-bindings read it. The switched
+            // value is the operand right after the guard list.
+            const guard = node.childForFieldName('alias');
+            const switched = codeChildren(node)[1] ?? null;
+            if (guard?.type === 'expression_list' &&
+                declaresName(guard, name) &&
+                !within(switched, ident)) {
+                return switched;
+            }
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether a mixed-import file's route receiver traces back to echo's
+ * constructor — `e := echo.New()` / `echo.Default()` with `echo` resolving to
+ * one of the file's verified echo import aliases — either directly or through
+ * enclosing `Group(...)` calls (`users := api.Group(…)` ← `api := e.Group(…)`
+ * ← `echo.New()`), the normal shape of grouped routes (review #7, #10).
+ * A parameter or method receiver counts by its declared type instead:
+ * `e *echo.Echo` / `g *echo.Group` (with `echo` one of those aliases) proves
+ * echo; any other type — gin's, or one the file cannot tie to echo — does not.
+ * Unrelated packages' `New()`, a local that shadows the echo import name, and
+ * anything else return false so the caller keeps the conservative
+ * last-argument fallback instead of guessing. Returns null when the Group chain exceeds MAX_GROUP_DEPTH or a
+ * binding on it is control-flow dependent (CONFLICT): the framework is then
+ * unprovable either way, so the caller declines the route.
+ */
+function receiverBindsToEchoConstructor(receiver, echoAliases, depth = 0) {
+    if (depth > MAX_GROUP_DEPTH)
+        return null;
+    // An identifier resolves through its binding; a chained `X.Group(…).Group(…)`
+    // operand is already a call and is inspected as-is.
+    const value = receiver.type === 'identifier' ? lookupBinding(receiver) : receiver;
+    if (value === CONFLICT)
+        return null;
+    if (isParamBinding(value))
+        return isEchoRouterType(value.param.childForFieldName('type'), echoAliases);
+    if (value?.type !== 'call_expression')
+        return false;
+    const fn = value.childForFieldName('function');
+    if (fn?.type !== 'selector_expression')
+        return false;
+    const field = fn.childForFieldName('field')?.text;
+    const operand = fn.childForFieldName('operand');
+    if (!operand)
+        return false;
+    if (field === 'New' || field === 'Default') {
+        return operand.type === 'identifier' && echoAliases.has(operand.text) && !isLocalName(operand);
+    }
+    if (field === 'Group') {
+        return receiverBindsToEchoConstructor(operand, echoAliases, depth + 1);
+    }
+    return false;
+}
+/** `*echo.Echo` / `echo.Echo` / `*echo.Group` with `echo` a verified echo import alias. */
+function isEchoRouterType(type, echoAliases) {
+    const named = type?.type === 'pointer_type' ? codeChildren(type)[0] : type;
+    if (named?.type !== 'qualified_type')
+        return false;
+    const pkg = named.childForFieldName('package')?.text;
+    const typeName = named.childForFieldName('name')?.text;
+    return !!pkg && echoAliases.has(pkg) && (typeName === 'Echo' || typeName === 'Group');
+}
+/**
+ * Whether `ident` names a local value rather than an imported package: a
+ * declaration in scope (with or without a value — `var echo Factory` shadows
+ * too) or a parameter/receiver of an enclosing function. Go lets either
+ * shadow a package qualifier (`func f(echo *Factory) { echo.New() }`).
+ */
+function isLocalName(ident) {
+    // lookupBinding covers parameters and receivers too (ParamBinding).
+    return lookupBinding(ident) !== undefined;
+}
+/**
+ * Joined `Group(...)` prefix of a route receiver; '' when it cannot be traced.
+ * Returns null when the chain exceeds MAX_GROUP_DEPTH, or when a binding on it
+ * is control-flow dependent (CONFLICT): a partial or stale prefix would emit
+ * a wrong path, so the caller declines the route instead.
+ */
+function groupPrefix(receiver, depth = 0) {
+    if (depth > MAX_GROUP_DEPTH)
+        return null;
+    const value = receiver.type === 'identifier' ? findBinding(receiver) : receiver;
+    if (value === CONFLICT)
+        return null;
+    const group = value ? asGroupCall(value) : null;
+    if (!group)
+        return '';
+    const outer = groupPrefix(group.parent, depth + 1);
+    return outer === null ? null : joinRoutePath(outer, group.prefix);
+}
 // ─── Provider: net/http `http.HandleFunc("/p", handler)` ─────────────
 const HANDLE_FUNC_PATTERNS = compilePatterns({
     name: 'go-handle-func',
@@ -120,29 +523,96 @@ export const GO_HTTP_PLUGIN = {
     language: Go,
     scan(tree) {
         const out = [];
-        // Framework providers: r.GET/POST/... with handler identifier
+        // Framework providers: r.GET/POST/... on an engine or (nested) route group
+        const imports = readFrameworkImports(tree.rootNode);
+        const echoOnly = imports.echo.size > 0 && imports.gin.size === 0;
+        const mixed = imports.echo.size > 0 && imports.gin.size > 0;
+        // Handler names declared more than once in this file (`(h *A) List` and
+        // `(o *B) List`): the emitted name is field-only, so these must resolve
+        // only when unique in the file instead of taking the first same-named row.
+        const declaredNames = new Map();
+        for (const decl of tree.rootNode.descendantsOfType([
+            'function_declaration',
+            'method_declaration',
+        ])) {
+            const declName = decl.childForFieldName('name')?.text;
+            if (declName)
+                declaredNames.set(declName, (declaredNames.get(declName) ?? 0) + 1);
+        }
         for (const match of runCompiledPatterns(FRAMEWORK_ROUTE_PATTERNS, tree)) {
             const methodNode = match.captures.http_method;
             const pathNode = match.captures.path;
-            const handlerNode = match.captures.handler;
+            const receiverNode = match.captures.receiver;
             if (!methodNode || !pathNode)
                 continue;
-            const path = unquoteLiteral(pathNode.text);
-            if (path === null)
+            const literalPath = stringLiteral(pathNode);
+            if (literalPath === null)
+                continue;
+            const argList = pathNode.parent;
+            if (argList?.type !== 'argument_list')
+                continue;
+            const args = codeChildren(argList);
+            if (args[0]?.id !== pathNode.id)
+                continue;
+            // The path is the first code argument, so everything after it is a handler or
+            // middleware candidate: echo's verb calls take the FIRST of those, gin's
+            // the LAST (see FRAMEWORK_ROUTE_PATTERNS / readFrameworkImports). The
+            // rule is chosen per call: an echo-only file is unambiguous; a
+            // mixed-import file takes the first argument only when the receiver
+            // provably traces to echo's constructor (directly or through enclosing
+            // Group() calls) — everything else keeps the last-argument anchor,
+            // gin's order and the safer default when the file proves nothing.
+            const rest = args.slice(1);
+            if (rest.length === 0)
                 continue;
+            const echoOrder = mixed
+                ? receiverNode
+                    ? receiverBindsToEchoConstructor(receiverNode, imports.echo)
+                    : false
+                : echoOnly;
+            // A Group chain deeper than MAX_GROUP_DEPTH proves neither the full
+            // prefix nor the framework order: decline rather than emit a guess.
+            if (echoOrder === null)
+                continue;
+            const prefix = receiverNode ? groupPrefix(receiverNode) : '';
+            if (prefix === null)
+                continue;
+            const handlerNode = echoOrder ? rest[0] : rest[rest.length - 1];
+            if (!HANDLER_ARG_TYPES.has(handlerNode.type))
+                continue;
+            const path = receiverNode ? joinRoutePath(prefix, literalPath) : literalPath;
             // An inline `func(){…}` handler has no name → emit `name: null` and a
             // `line` so it resolves to its containing/closure symbol by line-span
-            // containment (like a consumer). A named identifier handler keeps its
-            // name and resolves by name; `line` is harmless there.
+            // containment (like a consumer). A named handler keeps its name and
+            // resolves by name; `line` is harmless there. For a method value or a
+            // package-qualified function (`h.List`, `pkg.List`) that name is the
+            // field, and the operand (usually a local variable, not the receiver
+            // type) does not prove where `List` is declared — so the detection is
+            // marked qualifiedHandler: resolve only to a repo-wide unique `List`,
+            // never to a same-named local method that merely shares the name.
             const isInlineHandler = handlerNode?.type === 'func_literal';
+            const isQualified = handlerNode?.type === 'selector_expression';
+            const handlerName = isQualified
+                ? (handlerNode.childForFieldName('field')?.text ?? null)
+                : (handlerNode?.text ?? null);
             out.push({
                 role: 'provider',
                 framework: 'go-framework',
                 method: methodNode.text.toUpperCase(),
                 path,
-                name: isInlineHandler ? null : (handlerNode?.text ?? null),
+                name: isInlineHandler ? null : handlerName,
                 line: (handlerNode ?? pathNode).startPosition.row + 1,
                 confidence: 0.8,
+                ...(isQualified ? { qualifiedHandler: true } : {}),
+                // A bare name declared more than once in this file (a function and a
+                // method of the same name) resolves only when the file holds exactly
+                // one match, rather than binding to whichever row the graph lists first.
+                ...(!isQualified &&
+                    !isInlineHandler &&
+                    handlerName &&
+                    (declaredNames.get(handlerName) ?? 0) > 1
+                    ? { strictHandlerResolution: true }
+                    : {}),
             });
         }
         // net/http HandleFunc: default method GET
@@ -151,7 +621,7 @@ export const GO_HTTP_PLUGIN = {
             const handlerNode = match.captures.handler;
             if (!pathNode)
                 continue;
-            const path = unquoteLiteral(pathNode.text);
+            const path = stringLiteral(pathNode);
             if (path === null)
                 continue;
             // Inline `func(){…}` handler → resolve by containment (see go-framework
@@ -176,7 +646,7 @@ export const GO_HTTP_PLUGIN = {
             const httpMethod = HTTP_CLIENT_METHOD_TO_HTTP[fnNode.text];
             if (!httpMethod)
                 continue;
-            const path = unquoteLiteral(pathNode.text);
+            const path = stringLiteral(pathNode);
             if (path === null)
                 continue;
             out.push({
@@ -195,8 +665,8 @@ export const GO_HTTP_PLUGIN = {
             const pathNode = match.captures.path;
             if (!methodNode || !pathNode)
                 continue;
-            const method = unquoteLiteral(methodNode.text);
-            const path = unquoteLiteral(pathNode.text);
+            const method = stringLiteral(methodNode);
+            const path = stringLiteral(pathNode);
             if (method === null || path === null)
                 continue;
             out.push({
@@ -215,7 +685,7 @@ export const GO_HTTP_PLUGIN = {
             const pathNode = match.captures.path;
             if (!methodNode || !pathNode)
                 continue;
-            const path = unquoteLiteral(pathNode.text);
+            const path = stringLiteral(pathNode);
             if (path === null)
                 continue;
             out.push({

package/dist/core/group/extractors/http-patterns/types.d.ts

@@ -58,6 +58,14 @@ export interface HttpDetection {
     };
     /** Resolve only from the registration file or exact import target; never guess repo-wide. */
     strictHandlerResolution?: boolean;
+    /**
+     * The handler was designated through a qualifier the plugin cannot tie to a
+     * declaration (`recv.name`, `pkg.name`): `name` alone does not prove the
+     * handler lives in the registration file. Skip the file-scoped name lookup
+     * — a same-named but unrelated local symbol would win it — and accept only
+     * a repo-wide unique match, else keep the file-level fallback.
+     */
+    qualifiedHandler?: boolean;
     /**
      * The plugin saw a provider handler designator but could not prove its owner.
      * Prevents the orchestrator from treating it as an anonymous inline handler

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

@@ -580,13 +580,19 @@ export class HttpRouteExtractor {
                         return null;
                     return resolveSymbolByNameUnique(d.handlerImport.name);
                 }
-                const byName = d.strictHandlerResolution
-                    ? resolveFileSymbolByNameUnique(syms, d.name)
-                    : resolveSymbolByName(syms, d.name);
-                if (byName)
-                    return byName;
-                if (d.strictHandlerResolution)
-                    return null;
+                // A qualified designator (`recv.name`) does not prove the handler is
+                // declared in this file, so the file-first rung could bind an
+                // unrelated same-named local symbol: go straight to the unique
+                // repo-wide match.
+                if (!d.qualifiedHandler) {
+                    const byName = d.strictHandlerResolution
+                        ? resolveFileSymbolByNameUnique(syms, d.name)
+                        : resolveSymbolByName(syms, d.name);
+                    if (byName)
+                        return byName;
+                    if (d.strictHandlerResolution)
+                        return null;
+                }
                 const byGlobal = await resolveSymbolByNameUnique(d.name);
                 if (byGlobal)
                     return byGlobal;

package/dist/core/ingestion/route-extractors/go-gin-echo.js

@@ -24,6 +24,7 @@
  */
 import { goImportPackageName } from '../languages/go/import-package-name.js';
 import { GoRouteBindings } from '../languages/go/route-bindings.js';
+import { stringLiteral } from './go-shared.js';
 import { normalizeExtractedRoutePath } from './route-path.js';
 export const GIN_ROUTE_SOURCE = 'gin-route';
 export const ECHO_ROUTE_SOURCE = 'echo-route';
@@ -38,68 +39,6 @@ const VERBS = new Set([
 ]);
 const FUNCTION_TYPE_LIST = ['function_declaration', 'method_declaration', 'func_literal'];
 const FUNCTION_TYPES = new Set(FUNCTION_TYPE_LIST);
-function stringLiteral(node) {
-    if (!node || node.hasError)
-        return null;
-    const body = node.text.slice(1, -1);
-    // Go discards carriage returns in raw strings, including CRLF source files.
-    if (node.type === 'raw_string_literal')
-        return body.replace(/\r/g, '');
-    if (node.type !== 'interpreted_string_literal')
-        return null;
-    if (!body.includes('\\'))
-        return body;
-    const simple = {
-        a: '\x07',
-        b: '\b',
-        f: '\f',
-        n: '\n',
-        r: '\r',
-        t: '\t',
-        v: '\v',
-        '\\': '\\',
-        '"': '"',
-    };
-    const chunks = [];
-    const tokens = /\\(?:[abfnrtv\\"]|[0-7]{3}|x[\da-fA-F]{2}|u[\da-fA-F]{4}|U[\da-fA-F]{8})|[^\\"\n]+/g;
-    let consumed = 0;
-    for (const match of body.matchAll(tokens)) {
-        if (match.index !== consumed)
-            return null;
-        const token = match[0];
-        consumed += token.length;
-        if (!token.startsWith('\\')) {
-            chunks.push(Buffer.from(token));
-        }
-        else if (simple[token[1]] !== undefined) {
-            chunks.push(Buffer.from(simple[token[1]]));
-        }
-        else {
-            const octal = /[0-7]/.test(token[1]);
-            const value = Number.parseInt(token.slice(octal ? 1 : 2), octal ? 8 : 16);
-            if (octal || token[1] === 'x') {
-                // Octal and hex escapes encode bytes, not Unicode code points.
-                if (value > 255)
-                    return null;
-                chunks.push(Buffer.from([value]));
-            }
-            else {
-                if (value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
-                    return null;
-                chunks.push(Buffer.from(String.fromCodePoint(value)));
-            }
-        }
-    }
-    if (consumed !== body.length)
-        return null;
-    try {
-        // Arbitrary non-UTF-8 Go byte strings cannot be represented losslessly in a URL.
-        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
-    }
-    catch {
-        return null;
-    }
-}
 /** The framework this file routes with, when exactly one is imported. */
 function readImports(root) {
     let gin = null;

package/dist/core/ingestion/route-extractors/go-shared.d.ts

@@ -0,0 +1,23 @@
+import type { SyntaxNode } from 'tree-sitter';
+/**
+ * Go string-literal decoding shared by the Go route extractors on both
+ * layers: the ingestion extractor (`go-gin-echo.ts`, Strategy A) and the
+ * group-mode HTTP plugin (`group/extractors/http-patterns/go.ts`,
+ * Strategy B). Both sides must produce the SAME text for a route literal,
+ * or the same route lands under two different contract ids that never
+ * collide in the merge — a wrong-path duplicate that survives alongside
+ * the graph's correct entry.
+ *
+ * Go's semantics, per `strconv.Unquote`:
+ *   - interpreted (`"…"`) strings decode escapes (`\n`, `\x2f`, `ሴ`,
+ *     `\101`, …); hex and octal escapes encode BYTES, not code points;
+ *   - raw (`` `…` ``) strings have no escapes (a backslash is literal),
+ *     and Go discards carriage returns in them, including CRLF source files;
+ *   - a string that cannot be decoded to valid UTF-8 text (invalid escape,
+ *     non-UTF-8 bytes) returns null — callers decline instead of guessing,
+ *     since a URL cannot carry those bytes losslessly.
+ *
+ * Nodes that are not string literals (an identifier prefix, a rune
+ * literal, an errored subtree) also return null.
+ */
+export declare function stringLiteral(node: SyntaxNode | null | undefined): string | null;

package/dist/core/ingestion/route-extractors/go-shared.js

@@ -0,0 +1,83 @@
+/**
+ * Go string-literal decoding shared by the Go route extractors on both
+ * layers: the ingestion extractor (`go-gin-echo.ts`, Strategy A) and the
+ * group-mode HTTP plugin (`group/extractors/http-patterns/go.ts`,
+ * Strategy B). Both sides must produce the SAME text for a route literal,
+ * or the same route lands under two different contract ids that never
+ * collide in the merge — a wrong-path duplicate that survives alongside
+ * the graph's correct entry.
+ *
+ * Go's semantics, per `strconv.Unquote`:
+ *   - interpreted (`"…"`) strings decode escapes (`\n`, `\x2f`, `ሴ`,
+ *     `\101`, …); hex and octal escapes encode BYTES, not code points;
+ *   - raw (`` `…` ``) strings have no escapes (a backslash is literal),
+ *     and Go discards carriage returns in them, including CRLF source files;
+ *   - a string that cannot be decoded to valid UTF-8 text (invalid escape,
+ *     non-UTF-8 bytes) returns null — callers decline instead of guessing,
+ *     since a URL cannot carry those bytes losslessly.
+ *
+ * Nodes that are not string literals (an identifier prefix, a rune
+ * literal, an errored subtree) also return null.
+ */
+export function stringLiteral(node) {
+    if (!node || node.hasError)
+        return null;
+    const body = node.text.slice(1, -1);
+    // Go discards carriage returns in raw strings, including CRLF source files.
+    if (node.type === 'raw_string_literal')
+        return body.replace(/\r/g, '');
+    if (node.type !== 'interpreted_string_literal')
+        return null;
+    if (!body.includes('\\'))
+        return body;
+    const simple = {
+        a: '\x07',
+        b: '\b',
+        f: '\f',
+        n: '\n',
+        r: '\r',
+        t: '\t',
+        v: '\v',
+        '\\': '\\',
+        '"': '"',
+    };
+    const chunks = [];
+    const tokens = /\\(?:[abfnrtv\\"]|[0-7]{3}|x[\da-fA-F]{2}|u[\da-fA-F]{4}|U[\da-fA-F]{8})|[^\\"\n]+/g;
+    let consumed = 0;
+    for (const match of body.matchAll(tokens)) {
+        if (match.index !== consumed)
+            return null;
+        const token = match[0];
+        consumed += token.length;
+        if (!token.startsWith('\\')) {
+            chunks.push(Buffer.from(token));
+        }
+        else if (simple[token[1]] !== undefined) {
+            chunks.push(Buffer.from(simple[token[1]]));
+        }
+        else {
+            const octal = /[0-7]/.test(token[1]);
+            const value = Number.parseInt(token.slice(octal ? 1 : 2), octal ? 8 : 16);
+            if (octal || token[1] === 'x') {
+                // Octal and hex escapes encode bytes, not Unicode code points.
+                if (value > 255)
+                    return null;
+                chunks.push(Buffer.from([value]));
+            }
+            else {
+                if (value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
+                    return null;
+                chunks.push(Buffer.from(String.fromCodePoint(value)));
+            }
+        }
+    }
+    if (consumed !== body.length)
+        return null;
+    try {
+        // Arbitrary non-UTF-8 Go byte strings cannot be represented losslessly in a URL.
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.13-rc.74",
+  "version": "1.6.13-rc.76",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -52,6 +52,7 @@
     "serve": "tsx src/cli/index.ts serve",
     "dev": "tsx watch src/cli/index.ts",
     "test": "vitest run",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json",
     "test:unit": "vitest run test/unit",
     "pretest:integration": "node scripts/build.js",
     "test:integration": "vitest run test/integration",