gitnexus 1.6.9-rc.14 → 1.6.9-rc.16

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/nuxt-auto-imports.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Nuxt v4 auto-import resolution for the TypeScript scope-resolver.
+ *
+ * Nuxt and Nitro both make symbols available project-wide without explicit
+ * import statements. Two sources cover the common cases:
+ *
+ *   1. `.nuxt/imports.d.ts` - client/shared composables generated by Nuxt at
+ *      build time. Only entries whose source is a project-local relative path
+ *      (i.e. NOT a package in node_modules or a Nuxt runtime alias) are
+ *      indexed. These are project utils and composables the developer wrote.
+ *
+ *   2. `server/utils/**` - Nitro auto-imports all exports from this directory
+ *      tree into every `server/api/`, `server/routes/`, and
+ *      `server/middleware/` file. These are not included in `imports.d.ts`
+ *      because they are server-only.
+ *
+ * The two sources are kept in separate maps because their visibility scopes
+ * differ: app/client files do not see `server/utils`, while Nitro server
+ * handlers prefer same-named server utilities over client composables.
+ *
+ * Detection: if `.nuxt/imports.d.ts` is absent the repo is not a Nuxt project
+ * and this module returns null immediately, adding zero overhead to non-Nuxt
+ * analysis runs. The `server/utils` scan is only attempted when the Nuxt
+ * detection succeeds, so it also costs nothing for non-Nuxt repos.
+ *
+ * Limitations:
+ *   - Auto-import edges are still heuristic rather than type-checked. The
+ *     emitter tags them with confidence 0.75.
+ *   - Re-exports with non-matching aliases (e.g. `flatUnwrap as unwrapSlot`
+ *     where `flatUnwrap` is the graph node name) try both the original export
+ *     name and the local alias when looking up the graph node.
+ *   - Only direct exports are indexed; barrel re-exports that chain through
+ *     multiple files are not followed.
+ */
+export type NuxtAutoImportScope = 'client' | 'server';
+/** A single auto-imported symbol and where it lives in the repo. */
+export interface NuxtAutoImportEntry {
+    /** The name used at call sites (the alias when `export { X as Y }` form). */
+    readonly localName: string;
+    /** The original export name in the source file (before `as`). */
+    readonly exportName: string;
+    /** Repo-relative POSIX path to the source file (with extension). */
+    readonly sourceFile: string;
+    /** Which Nuxt/Nitro visibility scope supplied this entry. */
+    readonly scope: NuxtAutoImportScope;
+}
+/**
+ * Aggregated auto-import maps for one Nuxt workspace, keyed by the local
+ * name used in calling code. Client/shared entries come from
+ * `.nuxt/imports.d.ts`; server entries come from `server/utils`.
+ */
+export interface NuxtAutoImportConfig {
+    readonly clientByLocalName: ReadonlyMap<string, NuxtAutoImportEntry>;
+    readonly serverByLocalName: ReadonlyMap<string, NuxtAutoImportEntry>;
+}
+/**
+ * Load the Nuxt auto-import map for `repoRoot`.
+ *
+ * Returns null when:
+ *   - `.nuxt/imports.d.ts` does not exist (non-Nuxt project or pre-build), or
+ *   - the file exists but yields zero project-local entries and `server/utils`
+ *     is absent or empty.
+ *
+ * The `server/utils` scan is only attempted when `.nuxt/imports.d.ts` was
+ * successfully read, confirming this is an initialized Nuxt project. This
+ * avoids partial results from repos that have a `server/utils` directory but
+ * are not Nuxt projects.
+ */
+export declare function loadNuxtAutoImports(repoRoot: string): Promise<NuxtAutoImportConfig | null>;
+export declare function hasNuxtAutoImports(config: NuxtAutoImportConfig): boolean;
+export declare function getNuxtAutoImportEntry(config: NuxtAutoImportConfig, localName: string, callerFile: string): NuxtAutoImportEntry | undefined;
+export declare function isNitroServerRuntimeFile(filePath: string): boolean;

package/dist/core/ingestion/languages/typescript/nuxt-auto-imports.js

@@ -0,0 +1,315 @@
+/**
+ * Nuxt v4 auto-import resolution for the TypeScript scope-resolver.
+ *
+ * Nuxt and Nitro both make symbols available project-wide without explicit
+ * import statements. Two sources cover the common cases:
+ *
+ *   1. `.nuxt/imports.d.ts` - client/shared composables generated by Nuxt at
+ *      build time. Only entries whose source is a project-local relative path
+ *      (i.e. NOT a package in node_modules or a Nuxt runtime alias) are
+ *      indexed. These are project utils and composables the developer wrote.
+ *
+ *   2. `server/utils/**` - Nitro auto-imports all exports from this directory
+ *      tree into every `server/api/`, `server/routes/`, and
+ *      `server/middleware/` file. These are not included in `imports.d.ts`
+ *      because they are server-only.
+ *
+ * The two sources are kept in separate maps because their visibility scopes
+ * differ: app/client files do not see `server/utils`, while Nitro server
+ * handlers prefer same-named server utilities over client composables.
+ *
+ * Detection: if `.nuxt/imports.d.ts` is absent the repo is not a Nuxt project
+ * and this module returns null immediately, adding zero overhead to non-Nuxt
+ * analysis runs. The `server/utils` scan is only attempted when the Nuxt
+ * detection succeeds, so it also costs nothing for non-Nuxt repos.
+ *
+ * Limitations:
+ *   - Auto-import edges are still heuristic rather than type-checked. The
+ *     emitter tags them with confidence 0.75.
+ *   - Re-exports with non-matching aliases (e.g. `flatUnwrap as unwrapSlot`
+ *     where `flatUnwrap` is the graph node name) try both the original export
+ *     name and the local alias when looking up the graph node.
+ *   - Only direct exports are indexed; barrel re-exports that chain through
+ *     multiple files are not followed.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+const FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+const GENERATED_DIR_NAMES = new Set([
+    '.git',
+    '.nuxt',
+    '.output',
+    '.next',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+]);
+const IMPORTS_DTS_EXPORT_RE = /^export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/gm;
+const NITRO_DECLARATION_EXPORT_RE = /^export\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)|^export\s+(?:default\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm;
+const NITRO_VARIABLE_EXPORT_RE = /^export\s+(?:const|let|var)\s+([^;\n]+)/gm;
+// Matches the binding name at the head of a single declarator (`name`, `name:`, `name =`).
+// A leading `{`/`[` (destructuring) does not match, so destructured exports are skipped.
+const DECLARATOR_NAME_RE = /^\s*([A-Za-z_$][A-Za-z0-9_$]*)/;
+// ---- loader -----------------------------------------------------------------
+/**
+ * Load the Nuxt auto-import map for `repoRoot`.
+ *
+ * Returns null when:
+ *   - `.nuxt/imports.d.ts` does not exist (non-Nuxt project or pre-build), or
+ *   - the file exists but yields zero project-local entries and `server/utils`
+ *     is absent or empty.
+ *
+ * The `server/utils` scan is only attempted when `.nuxt/imports.d.ts` was
+ * successfully read, confirming this is an initialized Nuxt project. This
+ * avoids partial results from repos that have a `server/utils` directory but
+ * are not Nuxt projects.
+ */
+export async function loadNuxtAutoImports(repoRoot) {
+    const clientByLocalName = new Map();
+    const serverByLocalName = new Map();
+    const nuxtInitialized = await collectImportsDts(repoRoot, clientByLocalName);
+    // Only scan server/utils when imports.d.ts was present, confirming this is
+    // an initialized Nuxt project. Without this gate, a non-Nuxt repo with a
+    // server/utils directory would get spurious Nitro auto-import edges.
+    if (nuxtInitialized) {
+        await collectNitroServerUtils(repoRoot, serverByLocalName);
+    }
+    const config = { clientByLocalName, serverByLocalName };
+    return hasNuxtAutoImports(config) ? config : null;
+}
+export function hasNuxtAutoImports(config) {
+    return config.clientByLocalName.size > 0 || config.serverByLocalName.size > 0;
+}
+export function getNuxtAutoImportEntry(config, localName, callerFile) {
+    if (isNitroServerRuntimeFile(callerFile)) {
+        // Nitro auto-imports only `server/utils/**` into the server context; app
+        // `composables/` are Vue-app-only. Server callers therefore resolve the
+        // server map only — no client fallback, which would emit cross-context
+        // CALLS edges Nitro never actually creates.
+        return config.serverByLocalName.get(localName);
+    }
+    return config.clientByLocalName.get(localName);
+}
+/**
+ * Directories whose files run in the Nitro server context and so receive
+ * `server/utils` auto-imports without an explicit import: API routes, server
+ * routes, middleware, plugins, and (Nitro 2.6+) tasks.
+ */
+const NITRO_RUNTIME_DIR_PREFIXES = [
+    'server/api/',
+    'server/routes/',
+    'server/middleware/',
+    'server/plugins/',
+    'server/tasks/',
+];
+export function isNitroServerRuntimeFile(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return NITRO_RUNTIME_DIR_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+// ---- .nuxt/imports.d.ts -----------------------------------------------------
+/**
+ * Parse `.nuxt/imports.d.ts` and add project-local entries to `byLocalName`.
+ *
+ * The file contains lines of the form:
+ *   export { name1, name2, origName as alias } from 'source'
+ *
+ * Only entries with a source that is a project-local relative path
+ * (starts with `./` or `../` AND does not contain `node_modules`) are
+ * included. Nuxt runtime paths (`#app/...`) and third-party packages are
+ * intentionally skipped because they have no graph nodes in the repo.
+ *
+ * @returns true when `.nuxt/imports.d.ts` was successfully read.
+ */
+async function collectImportsDts(repoRoot, byLocalName) {
+    const importsPath = path.join(repoRoot, '.nuxt', 'imports.d.ts');
+    let content;
+    try {
+        content = await fs.readFile(importsPath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    const nuxtDir = path.join(repoRoot, '.nuxt');
+    IMPORTS_DTS_EXPORT_RE.lastIndex = 0;
+    let m;
+    while ((m = IMPORTS_DTS_EXPORT_RE.exec(content)) !== null) {
+        const symbolsRaw = m[1];
+        const source = m[2];
+        if (!isProjectLocalPath(source))
+            continue;
+        // Containment guard: a crafted source (`from '../../../../etc/passwd'`)
+        // passes the relative-path check but escapes the repo. Skip anything that
+        // resolves outside repoRoot before touching the filesystem.
+        const resolvedBase = path.resolve(nuxtDir, source);
+        if (!isWithinRepo(repoRoot, resolvedBase))
+            continue;
+        const resolvedFile = await resolveExtension(resolvedBase);
+        if (resolvedFile === null)
+            continue;
+        const sourceFile = toRepoPosix(repoRoot, resolvedFile);
+        for (const raw of symbolsRaw.split(',')) {
+            const trimmed = raw.trim();
+            if (!trimmed)
+                continue;
+            const asIdx = trimmed.indexOf(' as ');
+            const exportName = asIdx >= 0 ? trimmed.slice(0, asIdx).trim() : trimmed;
+            const localName = asIdx >= 0 ? trimmed.slice(asIdx + 4).trim() : trimmed;
+            if (!localName || !exportName)
+                continue;
+            if (!byLocalName.has(localName)) {
+                byLocalName.set(localName, { localName, exportName, sourceFile, scope: 'client' });
+            }
+        }
+    }
+    return true;
+}
+// ---- server/utils (Nitro auto-imports) --------------------------------------
+/**
+ * Scan `server/utils/**` and register every exported symbol as a Nitro
+ * auto-import. Nitro makes all exports from this directory tree available
+ * without an import statement in server routes and middleware.
+ */
+async function collectNitroServerUtils(repoRoot, byLocalName) {
+    const serverUtilsDir = path.join(repoRoot, 'server', 'utils');
+    if (!(await dirExists(serverUtilsDir)))
+        return;
+    const tsFiles = await collectTsFiles(serverUtilsDir);
+    for (const absPath of tsFiles) {
+        let content;
+        try {
+            content = await fs.readFile(absPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const sourceFile = toRepoPosix(repoRoot, absPath);
+        for (const name of extractNitroExportNames(content)) {
+            if (!byLocalName.has(name)) {
+                byLocalName.set(name, { localName: name, exportName: name, sourceFile, scope: 'server' });
+            }
+        }
+    }
+}
+// ---- helpers ----------------------------------------------------------------
+function isProjectLocalPath(source) {
+    if (!source.startsWith('./') && !source.startsWith('../'))
+        return false;
+    if (source.includes('node_modules'))
+        return false;
+    return true;
+}
+/** True when `absPath` is `repoRoot` itself or lives beneath it. */
+function isWithinRepo(repoRoot, absPath) {
+    const root = path.resolve(repoRoot);
+    return absPath === root || absPath.startsWith(root + path.sep);
+}
+async function resolveExtension(base) {
+    const directFile = await firstExistingFile([...FILE_EXTENSIONS.map((ext) => base + ext), base]);
+    if (directFile !== null)
+        return directFile;
+    return firstExistingFile(FILE_EXTENSIONS.map((ext) => path.join(base, `index${ext}`)));
+}
+async function firstExistingFile(candidates) {
+    const matches = await Promise.all(candidates.map(async (candidate) => ((await isFile(candidate)) ? candidate : null)));
+    return matches.find((candidate) => candidate !== null) ?? null;
+}
+async function isFile(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function toRepoPosix(repoRoot, absPath) {
+    return path.relative(repoRoot, absPath).replace(/\\/g, '/');
+}
+async function dirExists(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Recursively collect supported TypeScript/JavaScript files under a directory. */
+async function collectTsFiles(dir) {
+    const results = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory() && GENERATED_DIR_NAMES.has(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await collectTsFiles(full)));
+        }
+        else if (entry.isFile() && hasSupportedSourceExtension(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function hasSupportedSourceExtension(fileName) {
+    return FILE_EXTENSIONS.some((ext) => fileName.endsWith(ext));
+}
+function extractNitroExportNames(content) {
+    const names = new Set();
+    NITRO_DECLARATION_EXPORT_RE.lastIndex = 0;
+    let declaration;
+    while ((declaration = NITRO_DECLARATION_EXPORT_RE.exec(content)) !== null) {
+        const name = declaration[1] ?? declaration[2];
+        if (name)
+            names.add(name);
+    }
+    NITRO_VARIABLE_EXPORT_RE.lastIndex = 0;
+    let variableDeclaration;
+    while ((variableDeclaration = NITRO_VARIABLE_EXPORT_RE.exec(content)) !== null) {
+        // Only the LHS binding name of each top-level declarator is a Nitro export.
+        // Splitting on top-level commas and reading the leading identifier avoids
+        // capturing RHS tokens (arrow params, object keys, operands) as export names,
+        // and tolerates commas inside generic type annotations (`x: Map<a, b> = …`).
+        for (const declarator of splitTopLevelDeclarators(variableDeclaration[1])) {
+            const name = DECLARATOR_NAME_RE.exec(declarator);
+            if (name)
+                names.add(name[1]);
+        }
+    }
+    return [...names];
+}
+/**
+ * Split a `const`/`let`/`var` declarator list on top-level commas, tracking
+ * `()`, `[]`, `{}`, and `<>` nesting so commas inside call args, object/array
+ * literals, and generic type arguments do not split a declarator. Errs toward
+ * under-splitting on pathological RHS (a missed binding name, never a spurious
+ * one) — Nitro only auto-imports real top-level binding names.
+ */
+function splitTopLevelDeclarators(text) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '(' || ch === '[' || ch === '{' || ch === '<') {
+            depth++;
+        }
+        else if (ch === ')' || ch === ']' || ch === '}' || ch === '>') {
+            if (depth > 0)
+                depth--;
+        }
+        else if (ch === ',' && depth === 0) {
+            parts.push(text.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return parts;
+}

package/dist/core/ingestion/languages/typescript/scope-resolver.js

@@ -12,12 +12,24 @@
  * ./query.ts (TYPESCRIPT_SCOPE_QUERY constant).
  */
 import { SupportedLanguages } from '../../../../_shared/index.js';
+import { generateId } from '../../../../lib/utils.js';
 import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
 import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import { simpleKey } from '../../scope-resolution/graph-bridge/node-lookup.js';
 import { typescriptProvider } from '../typescript.js';
 import { loadTsconfigPaths } from '../../language-config.js';
 import { buildSuffixIndex } from '../../import-resolvers/utils.js';
 import { typescriptArityCompatibility, typescriptMergeBindings, resolveTsTarget, } from './index.js';
+import { getNuxtAutoImportEntry, hasNuxtAutoImports, loadNuxtAutoImports, } from './nuxt-auto-imports.js';
+const TYPESCRIPT_TYPE_ONLY_BINDING_TYPES = new Set([
+    'Interface',
+    'Type',
+    'TypeAlias',
+    'Typedef',
+    'Trait',
+    'Annotation',
+    'Decorator',
+]);
 /**
  * Build a `resolveImportTarget` adapter that memoizes the workspace
  * file list, the lower-cased file list, and the per-pass `resolveCache`
@@ -65,11 +77,14 @@ const typescriptScopeResolver = {
     importEdgeReason: 'typescript-scope: import',
     resolveImportTarget: makeTsResolveImportTarget(),
     // Threaded into `resolveImportTarget` so tsconfig path aliases
-    // (`@/services/user`, `~/x`, …) resolve through the same standard
+    // (`@/services/user`, `~/x`, ...) resolve through the same standard
     // resolver branch the legacy DAG uses. One I/O round-trip per
     // workspace pass; the orchestrator awaits this once.
+    // `nuxtAutoImports` is null for non-Nuxt projects (no .nuxt/imports.d.ts),
+    // so this adds zero overhead to ordinary TypeScript repos.
     loadResolutionConfig: async (repoPath) => ({
         tsconfigPaths: await loadTsconfigPaths(repoPath),
+        nuxtAutoImports: await loadNuxtAutoImports(repoPath),
     }),
     // TypeScript declaration merging + LEGB: local > import > wildcard,
     // separated by declaration space (value / type / namespace). The
@@ -95,23 +110,173 @@ const typescriptScopeResolver = {
     fieldFallbackOnMethodLookup: false,
     propagatesReturnTypesAcrossImports: true,
     // TypeScript uses `.values()` / `.keys()` method-call syntax for
-    // collection views — no property-style accessors like C#'s
+    // collection views -- no property-style accessors like C#'s
     // `Dictionary<K,V>.Values`. Leave `unwrapCollectionAccessor`
     // undefined and let the regular member-call branch handle them.
     //
-    // `collapseMemberCallsByCallerTarget` left undefined (= false) —
+    // `collapseMemberCallsByCallerTarget` left undefined (= false) --
     // TypeScript legacy DAG emits one edge per call site, so
     // per-site dedup is the parity target.
     //
-    // `populateNamespaceSiblings` left undefined — TypeScript requires
+    // `populateNamespaceSiblings` left undefined -- TypeScript requires
     // an explicit `import` / namespace augmentation for cross-file
     // visibility; there's no implicit same-namespace sibling rule
     // like C#'s.
     //
-    // `hoistTypeBindingsToModule` — `tsBindingScopeFor` DOES hoist
+    // `hoistTypeBindingsToModule` -- `tsBindingScopeFor` DOES hoist
     // method return-type bindings to the enclosing Module scope
     // (mirrors C#), so enable the walk-up that lets the compound-
     // receiver resolver find them.
     hoistTypeBindingsToModule: true,
+    /**
+     * Emit CALLS edges for Nuxt/Nitro auto-imported symbols that are used
+     * without an explicit import statement.
+     *
+     * Nuxt makes composables and server utils available project-wide via its
+     * auto-import system. Because no `import` statement exists, the standard
+     * scope-resolution passes cannot create call-graph edges for these symbols.
+     * This hook recovers those edges after all normal resolution has run.
+     *
+     * For each TypeScript file the hook:
+     *   1. Builds the set of files already explicitly imported (to avoid
+     *      creating duplicate edges for symbols imported conventionally).
+     *   2. Iterates parsed free-call reference sites and checks each against the
+     *      auto-import map selected for the caller's Nuxt/Nitro scope.
+     *   3. For each hit that is not shadowed by a local binding or explicit
+     *      import, emits a CALLS edge from the file's File node to the target
+     *      function node, and an IMPORTS edge from the caller file to the source
+     *      file (once per pair).
+     *
+     * Confidence is 0.75 (below the 0.9 used for fully resolved edges) to
+     * signal that these edges are heuristic rather than type-checked.
+     */
+    emitPostResolutionEdges(graph, parsedFiles, nodeLookup, indexes, ctx) {
+        const cfg = ctx.resolutionConfig;
+        const autoImports = cfg?.nuxtAutoImports;
+        if (!autoImports || !hasNuxtAutoImports(autoImports))
+            return;
+        // Pre-build a file -> explicit imported local names index so importing one
+        // symbol from a source does not suppress other auto-imported symbols from it.
+        const explicitImportNamesByFile = new Map();
+        for (const [scopeId, edges] of indexes.imports) {
+            const scope = indexes.scopeTree.getScope(scopeId);
+            if (!scope?.filePath)
+                continue;
+            let names = explicitImportNamesByFile.get(scope.filePath);
+            if (!names) {
+                names = new Set();
+                explicitImportNamesByFile.set(scope.filePath, names);
+            }
+            for (const edge of edges) {
+                // Record the local name whether or not the import resolved to a file.
+                // An explicit import of a name — even from an unresolved external
+                // package (`import { useAuto } from '@vueuse/core'`) — is authoritative
+                // shadowing intent and must suppress the auto-import for that name.
+                if (edge.localName)
+                    names.add(edge.localName);
+            }
+        }
+        for (const parsedFile of parsedFiles) {
+            const { filePath } = parsedFile;
+            if (!filePath.endsWith('.ts') && !filePath.endsWith('.tsx'))
+                continue;
+            const fileId = generateId('File', filePath);
+            const explicitImports = explicitImportNamesByFile.get(filePath) ?? new Set();
+            // Track (sourceFile) pairs already handled for this caller to avoid
+            // emitting duplicate IMPORTS edges and duplicate CALLS edges per symbol.
+            const emittedImports = new Set();
+            const emittedCalls = new Set();
+            for (const site of parsedFile.referenceSites) {
+                if (site.kind !== 'call' || site.callForm !== 'free')
+                    continue;
+                const localName = site.name;
+                const entry = getNuxtAutoImportEntry(autoImports, localName, filePath);
+                if (!entry)
+                    continue;
+                const { exportName, sourceFile } = entry;
+                // Skip when the file already binds this name explicitly, when the file
+                // IS the source, or when a lexical same-file binding shadows it.
+                if (explicitImports.has(localName) ||
+                    sourceFile === filePath ||
+                    hasLocalBindingInScopeChain(site.inScope, localName, filePath, indexes)) {
+                    continue;
+                }
+                // Emit one IMPORTS edge per (caller, sourceFile) pair.
+                if (!emittedImports.has(sourceFile)) {
+                    emittedImports.add(sourceFile);
+                    const targetFileId = generateId('File', sourceFile);
+                    if (graph.getNode(targetFileId)) {
+                        graph.addRelationship({
+                            id: generateId('IMPORTS', `${fileId}->nuxt-auto-import->${targetFileId}`),
+                            sourceId: fileId,
+                            targetId: targetFileId,
+                            type: 'IMPORTS',
+                            confidence: 0.75,
+                            reason: 'nuxt-auto-import-file',
+                        });
+                    }
+                }
+                // Emit one CALLS edge per (caller, symbol) pair.
+                const callKey = `${sourceFile}::${localName}`;
+                if (emittedCalls.has(callKey))
+                    continue;
+                emittedCalls.add(callKey);
+                // Look up the graph node by export name first, fall back to local name.
+                // The fallback handles `default as X` where the function is named X.
+                const targetNodeId = nodeLookup.get(simpleKey(sourceFile, exportName)) ??
+                    (exportName !== localName ? nodeLookup.get(simpleKey(sourceFile, localName)) : undefined);
+                if (!targetNodeId || !graph.getNode(targetNodeId))
+                    continue;
+                graph.addRelationship({
+                    id: generateId('CALLS', `${fileId}:nuxt-auto-import:${localName}->${targetNodeId}`),
+                    sourceId: fileId,
+                    targetId: targetNodeId,
+                    type: 'CALLS',
+                    confidence: 0.75,
+                    reason: 'nuxt-auto-import',
+                });
+            }
+        }
+    },
 };
+function occupiesTypeScriptValueSpace(type) {
+    return !TYPESCRIPT_TYPE_ONLY_BINDING_TYPES.has(type);
+}
+function hasLocalBindingInScopeChain(scopeId, name, filePath, indexes) {
+    const visited = new Set();
+    let cursor = scopeId;
+    while (cursor !== null && cursor !== undefined && !visited.has(cursor)) {
+        visited.add(cursor);
+        const scope = indexes.scopeTree.getScope(cursor);
+        if (!scope)
+            return false;
+        const localBindings = scope.bindings.get(name);
+        if (localBindings?.some((binding) => binding.origin === 'local' &&
+            binding.def.filePath === filePath &&
+            occupiesTypeScriptValueSpace(binding.def.type))) {
+            return true;
+        }
+        // Type-annotated function parameters — and other value-space type facts
+        // such as `self` and variable annotations — live in `scope.typeBindings`,
+        // not `scope.bindings`. A parameter named like a composable genuinely
+        // shadows the auto-import, and typeBindings never holds a pure type that
+        // belongs to callable space, so a same-file presence check here cannot
+        // over-suppress a legitimate auto-import.
+        //
+        // Residual (known limitation): this catches parameters whose annotation the
+        // TS scope query records as a type-binding (`p: Named`, generics, unions,
+        // predefined, arrays). Function-typed params (`p: () => void`), untyped
+        // params, destructured locals (`const { x } = …`), and catch-clause vars
+        // are captured by NEITHER map — the scope query emits no `@declaration` /
+        // `@type-binding` for them — so those shadow forms still leak an edge.
+        // Closing that needs shared TS scope-query/extractor changes that alter call
+        // resolution beyond Nuxt, so it is deferred to a follow-up rather than fixed
+        // here.
+        if (scope.filePath === filePath && scope.typeBindings.has(name)) {
+            return true;
+        }
+        cursor = scope.parent;
+    }
+    return false;
+}
 export { typescriptScopeResolver };

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/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.14",
+  "version": "1.6.9-rc.16",
   "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",