gitnexus 1.6.9-rc.13 → 1.6.9-rc.15

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

@@ -576,13 +576,16 @@ export const JAVA_HTTP_PLUGIN = {
     language: Java,
     // routeCoverage intentionally LEFT at the default 'partial' (#2138 Part 2).
     // The graph provider set is a strict *subset* of this scan()'s provider set —
-    // ingestion does NOT emit a Route node for (1) array-form `@GetMapping({...})`,
-    // (2) interface-inherited Spring routes, or (3) the 2nd verb of a same-URL
-    // GET+POST pair (Route nodes are URL-keyed). Declaring 'complete' here would
-    // let the parse-skip drop those group-only providers. Java flips to 'complete'
-    // only once ingestion provider extraction matches this scan (a follow-up:
-    // array-form query branch + interface-inheritance emission + per-verb Route
-    // identity). `hasConsumerSignals` below is kept ready for that flip.
+    // ingestion does NOT emit a Route node for (1) a method-level array route
+    // nested under a class-level array-form `@RequestMapping` (ingestion suppresses
+    // it rather than drop the prefix; bare/scalar-prefixed array methods ARE now
+    // emitted — see #2280), (2) interface-inherited Spring routes, or (3) the 2nd
+    // verb of a same-URL GET+POST pair (Route nodes are URL-keyed). Declaring
+    // 'complete' here would let the parse-skip drop those group-only providers.
+    // Java flips to 'complete' only once ingestion provider extraction matches this
+    // scan (a follow-up: class-level array-form prefix support + interface-
+    // inheritance emission + per-verb Route identity — tracked in #2280).
+    // `hasConsumerSignals` below is kept ready for that flip.
     // Consumer signals this plugin's scan() can detect: RestTemplate / WebClient /
     // OkHttp / Java-HttpClient / Apache-HttpClient call sites, OpenFeign
     // (`@FeignClient` + `@RequestLine`) interfaces, and Spring 6 HTTP Interface

package/dist/core/ingestion/languages/c-cpp.js

@@ -27,6 +27,7 @@ const FUNCTION_DECLARATION_TYPES = new Set([
     'generator_function_declaration',
     'function_item',
 ]);
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { cConfig as cFieldConfig, cppConfig as cppFieldConfig, } from '../field-extractors/configs/c-cpp.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
@@ -348,6 +349,8 @@ export const cProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(cVariableConfig),
     classExtractor: cClassExtractor,
+    // ── Doxygen doc comment → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     labelOverride: cppLabelOverride,
     builtInNames: C_BUILT_INS,
     // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
@@ -430,6 +433,8 @@ export const cppProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(cppVariableConfig),
     classExtractor: cppClassExtractor,
+    // ── Doxygen doc comment → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     labelOverride: cppLabelOverride,
     builtInNames: C_BUILT_INS,
     extractTemplateConstraints: extractCppTemplateConstraintsForProvider,

package/dist/core/ingestion/languages/csharp.js

@@ -14,6 +14,7 @@ import { csharpExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { csharpImportConfig } from '../import-resolvers/configs/csharp.js';
 import { CSHARP_QUERIES } from '../tree-sitter-queries.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { createCallExtractor } from '../call-extractors/generic.js';
 import { csharpCallConfig } from '../call-extractors/configs/csharp.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
@@ -180,6 +181,8 @@ export const csharpProvider = defineLanguage({
     methodExtractor: createMethodExtractor(csharpMethodConfig),
     variableExtractor: createVariableExtractor(csharpVariableConfig),
     classExtractor: createClassExtractor(csharpClassConfig),
+    // ── XML doc comments (`///`) → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     builtInNames: BUILT_INS,
     // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
     // C# is the second migration after Python. See ./csharp/index.ts for

package/dist/core/ingestion/languages/dart.js

@@ -8,7 +8,7 @@
  *     as a sibling of function_signature/method_signature (not as a child).
  *     The hook resolves the enclosing function by inspecting the previous sibling.
  */
-import { FUNCTION_NODE_TYPES } from '../utils/ast-helpers.js';
+import { createLeadingDocDescriptionExtractor, FUNCTION_NODE_TYPES, } from '../utils/ast-helpers.js';
 import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { dartClassConfig } from '../class-extractors/configs/dart.js';
@@ -108,6 +108,8 @@ export const dartProvider = defineLanguage({
     methodExtractor: createMethodExtractor(dartMethodConfig),
     variableExtractor: createVariableExtractor(dartVariableConfig),
     classExtractor: createClassExtractor(dartClassConfig),
+    // ── Dartdoc (`///`) → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     enclosingFunctionFinder: dartEnclosingFunctionFinder,
     builtInNames: DART_BUILT_INS,
     // ── Scope-based resolution hooks (RFC #909 Ring 3, issue #939) ──────────────

package/dist/core/ingestion/languages/go.js

@@ -10,6 +10,7 @@
 import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { goClassConfig } from '../class-extractors/configs/go.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { createGoCfgVisitor } from '../cfg/visitors/go.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as goConfig } from '../type-extractors/go.js';
@@ -126,6 +127,12 @@ export const goProvider = defineLanguage({
     methodExtractor: createMethodExtractor(goMethodConfig),
     variableExtractor: createVariableExtractor(goVariableConfig),
     classExtractor: createClassExtractor(goClassConfig),
+    // ── godoc (`//` leading comments) → description (issue #2270). Build/tool
+    //    directives (//go:…, // +build, //nolint, //line) are not documentation. ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor({
+        lineCommentPrefixes: ['//'],
+        lineDirectivePrefixes: ['//go:', '// +build', '//nolint', '//line'],
+    }),
     builtInNames: GO_BUILT_INS,
     // ── RFC #909 Ring 3: scope-based resolution hooks ──────────
     emitScopeCaptures: emitGoScopeCaptures,

package/dist/core/ingestion/languages/java.js

@@ -10,6 +10,7 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { javaClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { javaTypeConfig } from '../type-extractors/jvm.js';
 import { extractSpringRoutes } from '../route-extractors/spring.js';
 import { javaExportChecker } from '../export-detection.js';
@@ -94,6 +95,8 @@ export const javaProvider = defineLanguage({
     methodExtractor: createMethodExtractor(javaMethodConfig),
     variableExtractor: createVariableExtractor(javaVariableConfig),
     classExtractor: createClassExtractor(javaClassConfig),
+    // ── Javadoc → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     // ── RFC #909 Ring 3: scope-based resolution hooks ──
     emitScopeCaptures: emitJavaScopeCaptures,
     // ── PDG: per-function CFG + def/use harvest (#2195 U4) ──

package/dist/core/ingestion/languages/kotlin.js

@@ -10,6 +10,7 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { kotlinClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { assertCloneable } from '../workers/clone-safety.js';
 import { kotlinTypeConfig } from '../type-extractors/jvm.js';
 import { kotlinExportChecker } from '../export-detection.js';
@@ -153,6 +154,8 @@ export const kotlinProvider = defineLanguage({
     variableExtractor: createVariableExtractor(kotlinVariableConfig),
     classExtractor: createClassExtractor(kotlinClassConfig),
     builtInNames: BUILT_INS,
+    // ── KDoc → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     labelOverride: (functionNode, defaultLabel) => {
         if (defaultLabel !== 'Function')
             return defaultLabel;

package/dist/core/ingestion/languages/php.js

@@ -10,13 +10,13 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { phpClassConfig } from '../class-extractors/configs/php.js';
 import { createPhpCfgVisitor } from '../cfg/visitors/php.js';
-import { defineLanguage } from '../language-provider.js';
+import { defineLanguage, } from '../language-provider.js';
 import { typeConfig as phpConfig } from '../type-extractors/php.js';
 import { phpExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { phpImportConfig } from '../import-resolvers/configs/php.js';
 import { PHP_QUERIES } from '../tree-sitter-queries.js';
-import { findDescendant, extractStringContent } from '../utils/ast-helpers.js';
+import { findDescendant, extractStringContent, createLeadingDocDescriptionExtractor, } from '../utils/ast-helpers.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { phpConfig as phpFieldConfig } from '../field-extractors/configs/php.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
@@ -203,18 +203,29 @@ function extractEloquentRelationDescription(methodNode) {
         return relType;
     return null;
 }
+/** PHPDoc-docblock fallback, shared with the other leading-comment languages. */
+const phpLeadingDocFallback = createLeadingDocDescriptionExtractor();
 /**
  * LanguageProvider.descriptionExtractor implementation for PHP.
- * Extracts Eloquent model property metadata and relationship descriptions.
+ * Eloquent model property metadata and relationship descriptions take
+ * precedence (they are richer than prose); otherwise documentable symbols fall
+ * back to their leading PHPDoc docblock (issue #2270), mirroring the other
+ * leading-comment languages.
  */
 function phpDescriptionExtractor(nodeLabel, nodeName, captureMap) {
-    if (nodeLabel === 'Property' && captureMap['definition.property']) {
-        return extractPhpPropertyDescription(nodeName, captureMap['definition.property']) ?? undefined;
+    const propertyNode = captureMap['definition.property'];
+    if (nodeLabel === 'Property' && propertyNode) {
+        const eloquentProperty = extractPhpPropertyDescription(nodeName, propertyNode);
+        if (eloquentProperty)
+            return eloquentProperty;
     }
-    if (nodeLabel === 'Method' && captureMap['definition.method']) {
-        return extractEloquentRelationDescription(captureMap['definition.method']) ?? undefined;
+    const methodNode = captureMap['definition.method'];
+    if (nodeLabel === 'Method' && methodNode) {
+        const eloquentRelation = extractEloquentRelationDescription(methodNode);
+        if (eloquentRelation)
+            return eloquentRelation;
     }
-    return undefined;
+    return phpLeadingDocFallback(nodeLabel, nodeName, captureMap);
 }
 /** Detect Laravel route files by path convention. */
 function isPhpRouteFile(filePath) {

package/dist/core/ingestion/languages/ruby.js

@@ -10,6 +10,7 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { rubyClassConfig } from '../class-extractors/configs/ruby.js';
 import { defineLanguage } from '../language-provider.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { typeConfig as rubyConfig } from '../type-extractors/ruby.js';
 import { routeRubyCall } from '../call-routing.js';
 import { rubyExportChecker } from '../export-detection.js';
@@ -179,6 +180,20 @@ export const rubyProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(rubyVariableConfig),
     classExtractor: createClassExtractor(rubyClassConfig),
+    // ── Leading `#` comments (RDoc/YARD) → description (issue #2270). Magic
+    //    comments and the shebang are not documentation. ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor({
+        lineCommentPrefixes: ['#'],
+        lineDirectivePrefixes: [
+            '# frozen_string_literal:',
+            '# encoding:',
+            '# coding:',
+            '# -*-',
+            '#!',
+            '# rubocop:',
+            '# typed:',
+        ],
+    }),
     labelOverride: rubyLabelOverride,
     // Ruby MRO is kind-aware: prepend providers beat the class's own method,
     // which in turn beats include providers. The graph-level MRO phase

package/dist/core/ingestion/languages/rust.js

@@ -11,6 +11,7 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { rustClassConfig } from '../class-extractors/configs/rust.js';
 import { defineLanguage } from '../language-provider.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { typeConfig as rustConfig } from '../type-extractors/rust.js';
 import { rustExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
@@ -159,6 +160,13 @@ export const rustProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(rustVariableConfig),
     classExtractor: createClassExtractor(rustClassConfig),
+    // ── Rust outer doc comments (`///`, `/** */`) → description (issue #2270).
+    //    `//!` / `/*!` are INNER docs (document the enclosing item), so they must
+    //    not attach to the following item — opt out of both. ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor({
+        lineCommentPrefixes: ['///'],
+        blockDocPrefixes: ['/**'],
+    }),
     builtInNames: BUILT_INS,
     // ── RFC #909 Ring 3: scope-based resolution hooks ──────────
     emitScopeCaptures: emitRustScopeCaptures,

package/dist/core/ingestion/languages/swift.js

@@ -13,6 +13,7 @@ import { swiftExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { swiftImportConfig } from '../import-resolvers/configs/swift.js';
 import { SWIFT_QUERIES } from '../tree-sitter-queries.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { swiftConfig as swiftFieldConfig } from '../field-extractors/configs/swift.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
@@ -222,6 +223,8 @@ export const swiftProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(swiftVariableConfig),
     classExtractor: createClassExtractor(swiftClassConfig),
+    // ── Swift doc comments (`///`, `/** */`) → description (issue #2270) ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor(),
     orderSameNameTypeCandidates: orderSwiftSameNameTypeCandidates,
     builtInNames: BUILT_INS,
     // ── Scope-based resolution hooks (RFC #909 Ring 3, issue #937). See

package/dist/core/ingestion/languages/typescript.js

@@ -9,6 +9,7 @@ import { SupportedLanguages } from '../../../_shared/index.js';
 import { defineLanguage } from '../language-provider.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
 import { typescriptClassConfig, javascriptClassConfig, } from '../class-extractors/configs/typescript-javascript.js';
+import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { createTypeScriptCfgVisitor } from '../cfg/visitors/typescript.js';
 import { typeConfig as typescriptConfig } from '../type-extractors/typescript.js';
 import { tsExportChecker } from '../export-detection.js';
@@ -287,6 +288,11 @@ export const typescriptProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(typescriptVariableConfig),
     classExtractor: createClassExtractor(typescriptClassConfig),
+    // ── JSDoc → description (issue #2270). An exported decl is captured as the
+    //    inner declaration; its JSDoc precedes the wrapping `export_statement`. ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor({
+        wrapperNodeTypes: ['export_statement'],
+    }),
     builtInNames: BUILT_INS,
     // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
     // TypeScript is the third migration after Python and C#. See
@@ -347,6 +353,11 @@ export const javascriptProvider = defineLanguage({
     }),
     variableExtractor: createVariableExtractor(javascriptVariableConfig),
     classExtractor: createClassExtractor(javascriptClassConfig),
+    // ── JSDoc → description (issue #2270). An exported decl is captured as the
+    //    inner declaration; its JSDoc precedes the wrapping `export_statement`. ──
+    descriptionExtractor: createLeadingDocDescriptionExtractor({
+        wrapperNodeTypes: ['export_statement'],
+    }),
     builtInNames: BUILT_INS,
     // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
     // JavaScript is the fourth migration after Python, C#, and TypeScript.

package/dist/core/ingestion/route-extractors/spring.js

@@ -31,6 +31,18 @@ import { METHOD_ANNOTATION_TO_HTTP, isRouteMemberKey, findEnclosingClass, unquot
  *   @node  → enclosing declaration (class_declaration | method_declaration)
  *   @value → the string-literal argument
  *   @key   → the named-argument member key (absent for positional form)
+ *
+ * Method-level routes accept both the bare string form `@GetMapping("/x")` and
+ * the array form `@GetMapping({"/a","/b"})` (positional or `path =`/`value =`):
+ * a multi-element array yields one match per element, so the Phase 2 loop emits
+ * one route per path with no special-casing. This mirrors the group-layer
+ * `java.ts` query so the two Spring extractors stay in parity (#2138 follow-up;
+ * the divergence here was the root of the #2265 array-form gap). The class-level
+ * `@RequestMapping` branches also match the array form, but only to *detect* it:
+ * an array-form class prefix can't be resolved to a single string, so Phase 2
+ * suppresses that class's method-level array routes rather than emit them with a
+ * dropped prefix (a wrong route). Full class-array cross-product support is left
+ * to a follow-up (#2280).
  */
 const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
   [
@@ -38,7 +50,9 @@ const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
       (modifiers
         (annotation
           name: (identifier) @ann
-          arguments: (annotation_argument_list (string_literal) @value)))) @node
+          arguments: (annotation_argument_list
+            [(string_literal) @value
+             (element_value_array_initializer (string_literal) @value)])))) @node
     (class_declaration
       (modifiers
         (annotation
@@ -46,12 +60,15 @@ const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
           arguments: (annotation_argument_list
             (element_value_pair
               key: (identifier) @key
-              value: (string_literal) @value))))) @node
+              value: [(string_literal) @value
+                      (element_value_array_initializer (string_literal) @value)]))))) @node
     (method_declaration
       (modifiers
         (annotation
           name: (identifier) @ann
-          arguments: (annotation_argument_list (string_literal) @value)))) @node
+          arguments: (annotation_argument_list
+            [(string_literal) @value
+             (element_value_array_initializer (string_literal) @value)])))) @node
     (method_declaration
       (modifiers
         (annotation
@@ -59,7 +76,8 @@ const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
           arguments: (annotation_argument_list
             (element_value_pair
               key: (identifier) @key
-              value: (string_literal) @value))))) @node
+              value: [(string_literal) @value
+                      (element_value_array_initializer (string_literal) @value)]))))) @node
   ]
 `);
 /**
@@ -76,8 +94,15 @@ const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
  */
 export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
     const matches = ROUTE_ANNOTATION_QUERY.matches(tree.rootNode);
-    // Phase 1: collect class-level @RequestMapping prefixes keyed by node id
+    // Phase 1: collect class-level @RequestMapping prefixes keyed by node id.
+    // A scalar prefix (`@RequestMapping("/base")`) is stored in prefixByClassId.
+    // A class whose @RequestMapping uses the array form (`@RequestMapping({...})`)
+    // is instead recorded in classesWithArrayPrefix: there is no single prefix to
+    // store, and Phase 2 uses this to suppress that class's method-level array
+    // routes rather than emit them unprefixed (a wrong route — see #2280). Full
+    // class-array cross-product support is out of scope here.
     const prefixByClassId = new Map();
+    const classesWithArrayPrefix = new Set();
     for (const match of matches) {
         const caps = {};
         for (const { name, node } of match.captures) {
@@ -92,6 +117,10 @@ export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
         if (node.type === 'class_declaration' && annNode.text === 'RequestMapping') {
             if (!isRouteMemberKey(keyNode))
                 continue;
+            if (valueNode.parent?.type === 'element_value_array_initializer') {
+                classesWithArrayPrefix.add(node.id);
+                continue;
+            }
             const prefix = unquoteSpringLiteral(valueNode.text);
             if (prefix !== null)
                 prefixByClassId.set(node.id, prefix);
@@ -122,6 +151,18 @@ export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
         if (routePath === null)
             continue;
         const enclosingClass = findEnclosingClass(node);
+        // Suppress a method-level *array-form* route nested under a class-level
+        // array-form @RequestMapping. The class prefix is one of several values that
+        // cannot be resolved to a single string here, so emitting the route would
+        // drop the prefix and yield a wrong unprefixed Route (a false signal, worse
+        // than a missing one). Skipping keeps ingestion a strict subset of the group
+        // scan — safe under routeCoverage:'partial'. Full class-array cross-product
+        // support is tracked in #2280. (Scalar method paths under an array class
+        // prefix are left unchanged: that pre-existing divergence is out of scope.)
+        const isArrayElement = valueNode.parent?.type === 'element_value_array_initializer';
+        if (isArrayElement && enclosingClass && classesWithArrayPrefix.has(enclosingClass.id)) {
+            continue;
+        }
         const classPrefix = enclosingClass ? (prefixByClassId.get(enclosingClass.id) ?? '') : '';
         // `node` is the annotated `method_declaration`; its name field is the
         // handler method name (resolved to a symbol UID later by the routes phase).

package/dist/core/ingestion/utils/ast-helpers.d.ts

@@ -34,7 +34,7 @@ export declare const isQualifiableScopeLabel: (nodeLabel: string) => boolean;
  */
 export declare const DEFINITION_CAPTURE_KEYS: readonly ["definition.function", "definition.class", "definition.interface", "definition.method", "definition.struct", "definition.enum", "definition.namespace", "definition.module", "definition.trait", "definition.impl", "definition.type", "definition.const", "definition.static", "definition.variable", "definition.typedef", "definition.macro", "definition.union", "definition.property", "definition.record", "definition.delegate", "definition.annotation", "definition.constructor", "definition.template"];
 /** Extract the definition node from a tree-sitter query capture map. */
-export declare const getDefinitionNodeFromCaptures: (captureMap: Record<string, SyntaxNode>) => SyntaxNode | null;
+export declare const getDefinitionNodeFromCaptures: (captureMap: Record<string, SyntaxNode | undefined>) => SyntaxNode | null;
 type QueryMatchLike = {
     captures: Array<{
         name: string;
@@ -87,7 +87,7 @@ export declare function findAncestorBeforeBoundary(node: SyntaxNode, targetTypes
  * (e.g. C/C++ duplicate skipping, Kotlin Method promotion).
  * Returns null if the capture should be skipped (import, call, C/C++ duplicate, missing name).
  */
-export declare function getLabelFromCaptures(captureMap: Record<string, SyntaxNode>, provider: LanguageProvider): NodeLabel | null;
+export declare function getLabelFromCaptures(captureMap: Record<string, SyntaxNode | undefined>, provider: LanguageProvider): NodeLabel | null;
 /** Enclosing class info: both the generated node ID and the bare class name. */
 export interface EnclosingClassInfo {
     classId: string;
@@ -215,6 +215,85 @@ export declare function findDescendant(root: SyntaxNode, type: string): SyntaxNo
 export declare function extractStringContent(node: SyntaxNode | null | undefined): string | null;
 /** Find the first direct named child of a tree-sitter node matching the given type. */
 export declare function findChild(node: SyntaxNode, type: string): SyntaxNode | null;
+/**
+ * Extract the normalized text of a leading doc comment immediately preceding a
+ * definition node — covering both block doc comments (Javadoc / KDoc / JSDoc /
+ * PHPDoc / Doxygen, opened by `/**` or `/*!`) and runs of line doc comments
+ * (`///`, `//!`, or the caller-supplied prefixes such as Go's `//` or Ruby's
+ * `#`). Returns `undefined` when there is no preceding doc comment or it is
+ * empty.
+ *
+ * Grammar-agnostic by design: matches on the comment text prefix rather than a
+ * grammar node type, because the comment node is named differently across
+ * grammars (`block_comment`, `multiline_comment`, `comment`, `line_comment`).
+ * Annotations and modifiers live inside the definition node, so the doc comment
+ * remains the definition's `previousNamedSibling` even on annotated/decorated
+ * declarations.
+ *
+ * Block comments are taken as the immediately-preceding sibling (intervening
+ * package/import/code siblings already shield a file-level license block from
+ * the first declaration). Line doc comments enforce row-adjacency: the first
+ * comment must sit on the line directly above the definition, and each comment
+ * walked further up must sit directly above the previous one — so a run stops
+ * at a blank line. This matches godoc/RDoc/rustdoc convention and prevents an
+ * unrelated comment block (a license header, a Ruby shebang + magic comment)
+ * separated by a blank line from being absorbed. Adjacency is checked on
+ * `startPosition.row` (reliable) rather than `endPosition.row`, since some
+ * grammars fold the trailing newline into the comment node.
+ *
+ * Normalization mirrors Python docstring handling: strip the comment delimiters
+ * / per-line markers, then collapse whitespace to single spaces so tag content
+ * (`@param`, `@deprecated since 2.0, use computeBalanceV2`) survives.
+ *
+ * When the captured definition is an inner node and its own preceding sibling
+ * carries no doc, the search retries from a wrapping node whose type is listed in
+ * `opts.wrapperNodeTypes` (e.g. an `export_statement` wrapping an exported
+ * function/class — the JSDoc precedes the wrapper, not the inner declaration).
+ */
+export interface LeadingDocCommentOptions {
+    /** Line-comment doc prefixes (defaults to {@link DEFAULT_LINE_DOC_PREFIXES};
+     *  Go passes `['//']`, Ruby passes `['#']`). */
+    lineCommentPrefixes?: readonly string[];
+    /** Grammar node types that wrap a definition such that the doc comment is the
+     *  wrapper's preceding sibling rather than the definition's. TS/JS pass
+     *  `['export_statement']`. Empty by default → no wrapper retry. */
+    wrapperNodeTypes?: readonly string[];
+    /** Line-comment prefixes that are tool/build directives or magic comments
+     *  rather than documentation (Go passes `['//go:', '// +build', …]`, Ruby
+     *  passes `['# frozen_string_literal:', '#!', …]`). A matching line is skipped
+     *  in the doc run rather than absorbed. Empty by default. */
+    lineDirectivePrefixes?: readonly string[];
+    /** Block-comment doc openers (defaults to `['/**', '/*!']`). Rust passes
+     *  `['/**']` so its inner-doc `/*!` does not attach to the following item. */
+    blockDocPrefixes?: readonly string[];
+}
+export declare function extractLeadingDocComment(node: SyntaxNode, opts?: LeadingDocCommentOptions): string | undefined;
+/** Node labels that can carry a leading doc comment — callables and type-like
+ *  declarations. Field/property/variable/const doc is intentionally excluded
+ *  (issue #2270 scopes this to method/type documentation). Language-neutral:
+ *  a label a given grammar never emits simply never matches.
+ *
+ *  Bounded to labels that are also in `embeddings/types.ts` `EMBEDDABLE_LABELS`:
+ *  the description is only useful once it reaches the embedding metadata header,
+ *  and the embedding pipeline only queries embeddable labels. Extracting docs
+ *  for a non-embeddable label is a wasted write that never becomes searchable.
+ *  A subset invariant in the unit tests guards against drift. Making currently-
+ *  non-embeddable doc-bearing labels (Module, Delegate, Annotation, and C++
+ *  `Template`) searchable is tracked as a follow-up — it needs an embedding-
+ *  pipeline/schema change beyond this fix. */
+export declare const DOC_BEARING_LABELS: ReadonlySet<NodeLabel>;
+/**
+ * Build a `LanguageProvider.descriptionExtractor` that surfaces a definition's
+ * leading doc comment as its `description` (issue #2270). For labels in
+ * {@link DOC_BEARING_LABELS} (which is bounded to embeddable labels) the text
+ * then reaches the embedding metadata header and becomes semantically searchable.
+ *
+ * Language-neutral factory (names no language): guards on
+ * {@link DOC_BEARING_LABELS}; callers pass per-language doc-comment behavior via
+ * {@link LeadingDocCommentOptions} (line prefixes, export-style wrappers, …)
+ * which is threaded straight through to {@link extractLeadingDocComment}.
+ */
+export declare const createLeadingDocDescriptionExtractor: (opts?: LeadingDocCommentOptions) => ((nodeLabel: NodeLabel, nodeName: string, captureMap: Record<string, SyntaxNode | undefined>) => string | undefined);
 /** Convert a tree-sitter node to a `Capture` with 1-based line numbers
  *  (matching RFC §2.1). The tag includes the leading `@`. */
 export declare function nodeToCapture(name: string, node: SyntaxNode): Capture;

package/dist/core/ingestion/utils/ast-helpers.js

@@ -824,6 +824,148 @@ export function findChild(node, type) {
     }
     return null;
 }
+/** Remove bidi-override and zero-width control characters. Doc text is
+ *  attacker-influenced (any indexed repo) and is returned verbatim to MCP
+ *  clients, so strip Trojan-Source-style hidden controls from the description
+ *  before it leaves the extractor (#2286 review). Scoped to the doc-comment path
+ *  only — global `sanitizeUTF8` is intentionally untouched. */
+const stripBidiAndZeroWidth = (text) => Array.from(text)
+    .filter((ch) => {
+    const c = ch.codePointAt(0) ?? 0;
+    // Bidi overrides/isolates (U+202A–202E, U+2066–2069), zero-width
+    // space/joiners (U+200B–200D), and BOM/zero-width-no-break (U+FEFF).
+    return !((c >= 0x202a && c <= 0x202e) ||
+        (c >= 0x2066 && c <= 0x2069) ||
+        (c >= 0x200b && c <= 0x200d) ||
+        c === 0xfeff);
+})
+    .join('');
+/** Normalize a block doc comment body: strip the opening (double-star or
+ *  bang) delimiter, the closing delimiter, and per-line gutter stars, then
+ *  collapse whitespace so tag content stays as searchable words. */
+const normalizeBlockDocComment = (text) => {
+    const inner = stripBidiAndZeroWidth(text
+        .replace(/^\/\*[*!]/, '')
+        // Close delimiter: tolerate the degenerate empty comment `/**/`, where the
+        // opening strip already consumed the shared `*`, leaving a lone `/`.
+        .replace(/\*?\/\s*$/, '')
+        .replace(/^[ \t]*\*[ \t]?/gm, ' ')
+        .replace(/\s+/g, ' ')
+        .trim());
+    return inner.length > 0 ? inner : undefined;
+};
+/** Default line-comment prefixes treated as documentation: the universal
+ *  triple-slash / bang-slash doc markers (Rust, C#, Dart, Swift, Doxygen).
+ *  Go (`//`) and Ruby (`#`) opt into their conventional markers explicitly. */
+const DEFAULT_LINE_DOC_PREFIXES = ['///', '//!'];
+/** Default block-comment doc openers: Javadoc/JSDoc-style `/**` and Doxygen
+ *  `/*!`. Rust opts out of `/*!` (and `//!`) because those are *inner* docs that
+ *  document the enclosing item, not the following one. */
+const DEFAULT_BLOCK_DOC_PREFIXES = ['/**', '/*!'];
+/** A file-top `/** … *\/` license/copyright/file-overview block has no
+ *  package/import sibling to shield it, so it would otherwise be absorbed as the
+ *  first declaration's description (PR #2286 review). These markers identify such
+ *  headers; they are specific enough not to fire on an ordinary symbol doc that
+ *  merely mentions the word "copyright". `@file`/`@fileoverview` are explicitly
+ *  file-level JSDoc tags, so a block carrying them is not a symbol doc. */
+const FILE_HEADER_MARKER = /SPDX-License-Identifier|@licen[sc]e\b|@fileoverview\b|@file\b|Licen[sc]ed under|copyright\s*(\(c\)|©|\d{4})/i;
+export function extractLeadingDocComment(node, opts = {}) {
+    const lineCommentPrefixes = opts.lineCommentPrefixes ?? DEFAULT_LINE_DOC_PREFIXES;
+    const wrapperNodeTypes = opts.wrapperNodeTypes ?? [];
+    const lineDirectivePrefixes = opts.lineDirectivePrefixes ?? [];
+    const blockDocPrefixes = opts.blockDocPrefixes ?? DEFAULT_BLOCK_DOC_PREFIXES;
+    const fromNode = (anchor) => {
+        const prev = anchor.previousNamedSibling;
+        if (!prev)
+            return undefined;
+        // Block doc comment: /** ... */ or /*! ... */
+        if (blockDocPrefixes.some((p) => prev.text.startsWith(p))) {
+            // Skip a file-top license/copyright/overview header (no package/import
+            // sibling shields it from the first declaration). A strict row-adjacency
+            // check is unreliable here — some grammars fold the trailing newline into
+            // the comment node — so match header markers instead.
+            if (FILE_HEADER_MARKER.test(prev.text))
+                return undefined;
+            return normalizeBlockDocComment(prev.text);
+        }
+        // Run of row-adjacent preceding line doc comments (e.g. `///` or `//`).
+        const matchedPrefix = (text) => lineCommentPrefixes.find((prefix) => text.trimStart().startsWith(prefix));
+        const isDirective = (text) => lineDirectivePrefixes.some((prefix) => text.trimStart().startsWith(prefix));
+        const lines = [];
+        let current = prev;
+        let expectedRow = anchor.startPosition.row - 1;
+        while (current) {
+            const text = current.text;
+            const prefix = matchedPrefix(text);
+            if (prefix === undefined || current.startPosition.row !== expectedRow)
+                break;
+            // A build/tool directive or magic comment (e.g. `//go:build`,
+            // `# frozen_string_literal:`) is not documentation: skip it but keep
+            // walking the adjacent run, so a real doc above it is still collected.
+            if (!isDirective(text))
+                lines.unshift(text.trimStart().slice(prefix.length));
+            expectedRow = current.startPosition.row - 1;
+            current = current.previousNamedSibling;
+        }
+        const joined = stripBidiAndZeroWidth(lines.join(' ').replace(/\s+/g, ' ').trim());
+        return joined.length > 0 ? joined : undefined;
+    };
+    const direct = fromNode(node);
+    if (direct !== undefined)
+        return direct;
+    const parent = node.parent;
+    if (parent && wrapperNodeTypes.includes(parent.type)) {
+        return fromNode(parent);
+    }
+    return undefined;
+}
+/** Node labels that can carry a leading doc comment — callables and type-like
+ *  declarations. Field/property/variable/const doc is intentionally excluded
+ *  (issue #2270 scopes this to method/type documentation). Language-neutral:
+ *  a label a given grammar never emits simply never matches.
+ *
+ *  Bounded to labels that are also in `embeddings/types.ts` `EMBEDDABLE_LABELS`:
+ *  the description is only useful once it reaches the embedding metadata header,
+ *  and the embedding pipeline only queries embeddable labels. Extracting docs
+ *  for a non-embeddable label is a wasted write that never becomes searchable.
+ *  A subset invariant in the unit tests guards against drift. Making currently-
+ *  non-embeddable doc-bearing labels (Module, Delegate, Annotation, and C++
+ *  `Template`) searchable is tracked as a follow-up — it needs an embedding-
+ *  pipeline/schema change beyond this fix. */
+export const DOC_BEARING_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    'Class',
+    'Interface',
+    'Enum',
+    'Struct',
+    'Trait',
+    'Record',
+    'Union',
+    'Namespace',
+    'TypeAlias',
+    'Macro',
+]);
+/**
+ * Build a `LanguageProvider.descriptionExtractor` that surfaces a definition's
+ * leading doc comment as its `description` (issue #2270). For labels in
+ * {@link DOC_BEARING_LABELS} (which is bounded to embeddable labels) the text
+ * then reaches the embedding metadata header and becomes semantically searchable.
+ *
+ * Language-neutral factory (names no language): guards on
+ * {@link DOC_BEARING_LABELS}; callers pass per-language doc-comment behavior via
+ * {@link LeadingDocCommentOptions} (line prefixes, export-style wrappers, …)
+ * which is threaded straight through to {@link extractLeadingDocComment}.
+ */
+export const createLeadingDocDescriptionExtractor = (opts = {}) => {
+    return (nodeLabel, _nodeName, captureMap) => {
+        if (!DOC_BEARING_LABELS.has(nodeLabel))
+            return undefined;
+        const definitionNode = getDefinitionNodeFromCaptures(captureMap);
+        return definitionNode ? extractLeadingDocComment(definitionNode, opts) : undefined;
+    };
+};
 // ============================================================================
 // Capture + range helpers (formerly python/ast-utils.ts — language-agnostic)
 // ============================================================================

package/dist/core/ingestion/workers/parse-worker.js

@@ -1589,7 +1589,19 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                 }
             }
             const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}${parameterShapeTag}${constraintsTag}`);
-            const description = provider.descriptionExtractor?.(nodeLabel, nodeName, captureMap);
+            let description;
+            try {
+                description = provider.descriptionExtractor?.(nodeLabel, nodeName, captureMap);
+            }
+            catch (err) {
+                // A throw here (an unexpected tree-sitter node shape, a provider bug) must
+                // NOT propagate — it would escape processFileGroup to the language-group
+                // catch, which treats any throw as "parser unavailable" and silently drops
+                // every remaining file in the group. Mirrors the extractTemplateConstraints
+                // guard above (#2286 review).
+                reportWarning(`Description extraction failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
+                description = undefined;
+            }
             let frameworkHint = definitionNode
                 ? detectFrameworkFromAST(language, (definitionNode.text || '').slice(0, 300))
                 : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.13",
+  "version": "1.6.9-rc.15",
   "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",