gitnexus 1.6.3-rc.21 → 1.6.3-rc.23

package/dist/cli/ai-context.js

@@ -89,7 +89,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
 
-This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For blast radius across repository boundaries, use MCP tools \`group_impact\`, \`group_sync\`, \`group_query\`, \`group_contracts\`, \`group_status\`, and \`group_list\`. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
+This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
 
 `
         : ''}## CLI

package/dist/cli/group.js

@@ -149,6 +149,79 @@ export function registerGroupCommands(program) {
             console.log(`\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`);
         }
     });
+    group
+        .command('impact <name>')
+        .description('Cross-repo impact for a symbol in one member repo of a group')
+        .requiredOption('--target <symbol>', 'Symbol or file name to analyze')
+        .requiredOption('--repo <groupPath>', 'Member path from group.yaml (e.g. app/backend), not the indexed repo name')
+        .option('--direction <dir>', 'upstream or downstream', 'upstream')
+        .option('--service <path>', 'Optional monorepo service directory prefix (path filter)')
+        .option('--subgroup <path>', 'Optional prefix limiting which group repos participate in cross fan-out')
+        .option('--max-depth <n>', 'Max graph traversal depth')
+        .option('--cross-depth <n>', 'Cross-repository hop depth')
+        .option('--min-confidence <n>', 'Minimum relation confidence (0–1)')
+        .option('--include-tests', 'Include test files in traversal', false)
+        .option('--timeout-ms <n>', 'Phase-1 local impact wall time in milliseconds')
+        .option('--json', 'JSON output')
+        .action(async (name, opts) => {
+        const { LocalBackend } = await import('../mcp/local/local-backend.js');
+        const backend = new LocalBackend();
+        try {
+            await backend.init();
+            const payload = {
+                name,
+                repo: opts.repo,
+                target: opts.target,
+                direction: opts.direction || 'upstream',
+            };
+            if (opts.service)
+                payload.service = opts.service;
+            if (opts.subgroup)
+                payload.subgroup = opts.subgroup;
+            if (opts.maxDepth !== undefined && opts.maxDepth !== '') {
+                const n = parseInt(String(opts.maxDepth), 10);
+                if (!Number.isNaN(n))
+                    payload.maxDepth = n;
+            }
+            if (opts.crossDepth !== undefined && opts.crossDepth !== '') {
+                const n = parseInt(String(opts.crossDepth), 10);
+                if (!Number.isNaN(n))
+                    payload.crossDepth = n;
+            }
+            if (opts.minConfidence !== undefined && opts.minConfidence !== '') {
+                const n = parseFloat(String(opts.minConfidence));
+                if (!Number.isNaN(n))
+                    payload.minConfidence = n;
+            }
+            if (opts.timeoutMs !== undefined && opts.timeoutMs !== '') {
+                const n = parseInt(String(opts.timeoutMs), 10);
+                if (!Number.isNaN(n))
+                    payload.timeoutMs = n;
+            }
+            if (opts.includeTests)
+                payload.includeTests = true;
+            const raw = await backend.getGroupService().groupImpact(payload);
+            if (raw && typeof raw === 'object' && 'error' in raw) {
+                console.error(String(raw.error));
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(raw, null, 2));
+            }
+            else {
+                const summary = raw?.summary;
+                const risk = raw?.risk;
+                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}`);
+                if (summary) {
+                    console.log(`  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}`);
+                }
+            }
+        }
+        finally {
+            await backend.dispose().catch(() => { });
+        }
+    });
     group
         .command('query <name> <query>')
         .description('Search execution flows across all repos in a group')

package/dist/core/embeddings/chunker.js

@@ -10,6 +10,7 @@ export { characterChunk } from './character-chunk.js';
 import { characterChunk } from './character-chunk.js';
 import { ensureAndParse, findDeclarationNode, findFunctionNode } from './ast-utils.js';
 import { buildLineIndex, resolveChunkLines } from './line-index.js';
+import { CHUNKING_RULES, CHUNK_MODE_AST_DECLARATION, CHUNK_MODE_AST_FUNCTION, } from './types.js';
 /**
  * Main chunkNode function: dispatches by label
  */
@@ -27,26 +28,24 @@ export const chunkNode = async (label, content, filePath, startLine, endLine, ch
             },
         ];
     }
-    // Only function-like labels get AST chunking
-    if (label === 'Function' || label === 'Method' || label === 'Constructor') {
-        try {
-            const astChunks = await astChunk(content, filePath, startLine, endLine, chunkSize, overlap);
+    const rule = CHUNKING_RULES[label];
+    if (!rule) {
+        return characterChunk(content, startLine, endLine, chunkSize, overlap);
+    }
+    try {
+        if (rule.mode === CHUNK_MODE_AST_FUNCTION) {
+            const astChunks = await astChunk(content, filePath, startLine, endLine, chunkSize, overlap, rule);
             if (astChunks.length > 0)
                 return astChunks;
         }
-        catch {
-            // AST parsing failed — fall through to character fallback
-        }
-    }
-    if (label === 'Class' || label === 'Interface') {
-        try {
-            const declarationChunks = await declarationChunk(label, content, filePath, startLine, endLine, chunkSize, overlap);
+        if (rule.mode === CHUNK_MODE_AST_DECLARATION) {
+            const declarationChunks = await declarationChunk(content, filePath, startLine, endLine, chunkSize, overlap, rule);
             if (declarationChunks.length > 0)
                 return declarationChunks;
         }
-        catch {
-            // AST parsing failed — fall through to character fallback
-        }
+    }
+    catch {
+        // AST parsing failed — fall through to character fallback
     }
     // Character-based fallback for everything else
     return characterChunk(content, startLine, endLine, chunkSize, overlap);
@@ -56,7 +55,7 @@ export const chunkNode = async (label, content, filePath, startLine, endLine, ch
  * Parse snippet content, locate the function declaration node,
  * split body by statement boundaries.
  */
-const astChunk = async (content, filePath, startLine, endLine, chunkSize, overlap) => {
+const astChunk = async (content, filePath, startLine, endLine, chunkSize, overlap, rule) => {
     const tree = await ensureAndParse(content, filePath);
     if (!tree)
         return [];
@@ -84,7 +83,7 @@ const astChunk = async (content, filePath, startLine, endLine, chunkSize, overla
     }
     if (statements.length === 0)
         return [];
-    return chunkByUnits(content, lineOffsets, startLine, chunkSize, overlap, statements, targetNode.startIndex, targetNode.endIndex, true, true);
+    return chunkByUnits(content, lineOffsets, startLine, chunkSize, overlap, statements, targetNode.startIndex, targetNode.endIndex, rule.includePrefix, rule.includeSuffix);
 };
 const DECLARATION_BODY_NODE_TYPES = new Set([
     'class_body',
@@ -102,7 +101,7 @@ const FIELD_LIKE_MEMBER_TYPES = new Set([
     'pair',
     'enum_assignment',
 ]);
-const declarationChunk = async (label, content, filePath, startLine, endLine, chunkSize, overlap) => {
+const declarationChunk = async (content, filePath, startLine, endLine, chunkSize, overlap, rule) => {
     const tree = await ensureAndParse(content, filePath);
     if (!tree)
         return [];
@@ -112,10 +111,10 @@ const declarationChunk = async (label, content, filePath, startLine, endLine, ch
     const bodyNode = getDeclarationBodyNode(targetNode);
     if (!bodyNode)
         return [];
-    const members = collectDeclarationUnits(bodyNode, label);
+    const members = collectDeclarationUnits(bodyNode, rule.groupFields);
     if (members.length === 0)
         return [];
-    return chunkByUnits(content, buildLineIndex(content), startLine, chunkSize, overlap, members, targetNode.startIndex, targetNode.endIndex, false, false);
+    return chunkByUnits(content, buildLineIndex(content), startLine, chunkSize, overlap, members, targetNode.startIndex, targetNode.endIndex, rule.includePrefix, rule.includeSuffix);
 };
 const buildChunk = (content, lineOffsets, chunkIndex, startOffset, endOffset, baseStartLine) => {
     const lineRange = resolveChunkLines(lineOffsets, startOffset, endOffset, baseStartLine);
@@ -150,12 +149,18 @@ const chunkByUnits = (content, lineOffsets, baseStartLine, chunkSize, overlap, u
         }
         if (candidateEndOffset - chunkStartOffset > chunkSize) {
             const oversizedUnit = units[chunkStartUnitIdx];
-            const oversizedLineRange = resolveChunkLines(lineOffsets, oversizedUnit.startIndex, oversizedUnit.endIndex, baseStartLine);
-            const oversizedChunks = characterChunk(content.slice(oversizedUnit.startIndex, oversizedUnit.endIndex), oversizedLineRange.startLine, oversizedLineRange.endLine, chunkSize, overlap).map((chunk, offsetIdx) => ({
+            const oversizedStartOffset = chunkStartUnitIdx === 0 && includeContainerPrefixOnFirstChunk
+                ? containerStartOffset
+                : oversizedUnit.startIndex;
+            const oversizedEndOffset = chunkStartUnitIdx === units.length - 1 && includeContainerSuffixOnLastChunk
+                ? containerEndOffset
+                : oversizedUnit.endIndex;
+            const oversizedLineRange = resolveChunkLines(lineOffsets, oversizedStartOffset, oversizedEndOffset, baseStartLine);
+            const oversizedChunks = characterChunk(content.slice(oversizedStartOffset, oversizedEndOffset), oversizedLineRange.startLine, oversizedLineRange.endLine, chunkSize, overlap).map((chunk, offsetIdx) => ({
                 ...chunk,
                 chunkIndex: chunks.length + offsetIdx,
-                startOffset: chunk.startOffset + oversizedUnit.startIndex,
-                endOffset: chunk.endOffset + oversizedUnit.startIndex,
+                startOffset: chunk.startOffset + oversizedStartOffset,
+                endOffset: chunk.endOffset + oversizedStartOffset,
             }));
             chunks.push(...oversizedChunks);
             chunkStartUnitIdx += 1;
@@ -200,7 +205,7 @@ const getDeclarationBodyNode = (node) => {
     }
     return null;
 };
-const collectDeclarationUnits = (bodyNode, label) => {
+const collectDeclarationUnits = (bodyNode, groupFields) => {
     const members = [];
     for (let i = 0; i < bodyNode.namedChildCount; i++) {
         const child = bodyNode.namedChild(i);
@@ -209,7 +214,7 @@ const collectDeclarationUnits = (bodyNode, label) => {
         members.push({
             startIndex: child.startIndex,
             endIndex: child.endIndex,
-            groupable: label === 'Class' && FIELD_LIKE_MEMBER_TYPES.has(child.type),
+            groupable: groupFields && FIELD_LIKE_MEMBER_TYPES.has(child.type),
         });
     }
     if (members.length === 0)

package/dist/core/embeddings/embedding-pipeline.d.ts

@@ -9,6 +9,12 @@
  * 5. Create vector index for semantic search
  */
 import { type EmbeddingProgress, type EmbeddingConfig, type EmbeddableNode, type SemanticSearchResult, type EmbeddingContext } from './types.js';
+/**
+ * Bump this when the embedding text template changes in a way that should
+ * invalidate existing vectors, such as metadata/header shape changes,
+ * structural container context changes, or preceding-context formatting rules.
+ */
+export declare const EMBEDDING_TEXT_VERSION = "v2";
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors

package/dist/core/embeddings/embedding-pipeline.js

@@ -13,10 +13,16 @@ import { initEmbedder, embedBatch, embedText, embeddingToArray, isEmbedderReady,
 import { generateEmbeddingText } from './text-generator.js';
 import { chunkNode, characterChunk } from './chunker.js';
 import { extractStructuralNames } from './structural-extractor.js';
-import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, isShortLabel, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
+import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS, isShortLabel, LABEL_METHOD, LABELS_WITH_EXPORTED, STRUCTURAL_LABELS, collectBestChunks, } from './types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
 const isDev = process.env.NODE_ENV === 'development';
+/**
+ * Bump this when the embedding text template changes in a way that should
+ * invalidate existing vectors, such as metadata/header shape changes,
+ * structural container context changes, or preceding-context formatting rules.
+ */
+export const EMBEDDING_TEXT_VERSION = 'v2';
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors
@@ -27,8 +33,9 @@ export const contentHashForNode = (node, config = {}) => {
     // Hash must be deterministic across runs, so exclude methodNames/fieldNames
     // which are populated during the batch loop via AST extraction.
     // Using only node.content ensures the hash stays stable.
+    // NOTE: A change to extractStructuralNames behavior requires bumping EMBEDDING_TEXT_VERSION.
     const text = generateEmbeddingText({ ...node, methodNames: undefined, fieldNames: undefined }, node.content, config);
-    return createHash('sha1').update(text).digest('hex');
+    return createHash('sha1').update(EMBEDDING_TEXT_VERSION).update('\n').update(text).digest('hex');
 };
 /**
  * Query all embeddable nodes from LadybugDB
@@ -39,7 +46,7 @@ const queryEmbeddableNodes = async (executeQuery) => {
     for (const label of EMBEDDABLE_LABELS) {
         try {
             let query;
-            if (label === 'Method') {
+            if (label === LABEL_METHOD) {
                 // Method has parameterCount and returnType
                 query = `
           MATCH (n:Method)
@@ -72,7 +79,7 @@ const queryEmbeddableNodes = async (executeQuery) => {
             }
             const rows = await executeQuery(query);
             for (const row of rows) {
-                const hasExportedColumn = label === 'Method' || LABELS_WITH_EXPORTED.has(label);
+                const hasExportedColumn = label === LABEL_METHOD || LABELS_WITH_EXPORTED.has(label);
                 allNodes.push({
                     id: row.id ?? row[0],
                     name: row.name ?? row[1],
@@ -83,7 +90,7 @@ const queryEmbeddableNodes = async (executeQuery) => {
                     endLine: row.endLine ?? row[6],
                     isExported: hasExportedColumn ? (row.isExported ?? row[7]) : undefined,
                     description: row.description ?? (hasExportedColumn ? row[8] : row[7]),
-                    ...(label === 'Method'
+                    ...(label === LABEL_METHOD
                         ? {
                             parameterCount: row.parameterCount ?? row[9],
                             returnType: row.returnType ?? row[10],
@@ -301,8 +308,9 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                         chunks = characterChunk(node.content, startLine, endLine, chunkSize, overlap);
                     }
                 }
+                let prevTail = '';
                 for (const chunk of chunks) {
-                    const text = generateEmbeddingText(node, chunk.text, finalConfig);
+                    const text = generateEmbeddingText(node, chunk.text, finalConfig, chunk.chunkIndex, prevTail);
                     allTexts.push(text);
                     allUpdates.push({
                         nodeId: node.id,
@@ -311,6 +319,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                         endLine: chunk.endLine,
                         contentHash: hash,
                     });
+                    prevTail = overlap > 0 ? chunk.text.slice(-overlap) : '';
                 }
             }
             // Embed chunk texts in sub-batches to control memory

package/dist/core/embeddings/text-generator.d.ts

@@ -24,7 +24,7 @@ export declare const extractDeclarationOnly: (content: string) => string;
  * Generate embedding text for any embeddable node
  * Dispatches to the appropriate generator based on node label
  */
-export declare const generateEmbeddingText: (node: EmbeddableNode, codeBody: string, config?: Partial<EmbeddingConfig>) => string;
+export declare const generateEmbeddingText: (node: EmbeddableNode, codeBody: string, config?: Partial<EmbeddingConfig>, chunkIndex?: number, prevTail?: string) => string;
 /**
  * Export truncation helper for testing
  */

package/dist/core/embeddings/text-generator.js

@@ -8,7 +8,7 @@
  * Method/field names for Class nodes are extracted by the ingestion
  * pipeline's AST extractors and passed via node.methodNames/node.fieldNames.
  */
-import { DEFAULT_EMBEDDING_CONFIG, isShortLabel } from './types.js';
+import { CHUNKING_RULES, DEFAULT_EMBEDDING_CONFIG, STRUCTURAL_TEXT_MODE_DECLARATION, isShortLabel, } from './types.js';
 /**
  * Truncate description to max length at sentence/word boundary
  */
@@ -71,34 +71,45 @@ const buildMetadataHeader = (node, config) => {
     }
     return parts.join('\n');
 };
-const generateCodeBodyText = (node, codeBody, config) => {
+const generateCodeBodyText = (node, codeBody, config, prevTail) => {
     const header = buildMetadataHeader(node, config);
-    const cleaned = cleanContent(codeBody);
-    return `${header}\n\n${cleaned}`;
+    const parts = [header];
+    if (prevTail) {
+        parts.push(`[preceding context]: ...${cleanContent(prevTail)}`);
+    }
+    parts.push('', cleanContent(codeBody));
+    return parts.join('\n');
 };
-/**
- * Generate embedding text for Class nodes
- * Signature + properties + method name list only (no method bodies)
- * Method/field names come from AST extractors via node.methodNames/node.fieldNames.
- */
-const generateClassText = (node, codeBody, config) => {
-    return generateStructuralTypeText(node, codeBody, config);
+const getCompactContainerContext = (cleanedContent, declarationOnly) => {
+    const source = declarationOnly || cleanedContent;
+    const nlIdx = source.indexOf('\n');
+    const firstLine = (nlIdx === -1 ? source : source.substring(0, nlIdx)).trim();
+    return firstLine ? `Container: ${firstLine}` : undefined;
 };
-const generateStructuralTypeText = (node, codeBody, config) => {
+const generateStructuralTypeText = (node, codeBody, config, chunkIndex, prevTail) => {
     const header = buildMetadataHeader(node, config);
     const parts = [header];
-    if (node.methodNames?.length) {
+    const isFirstChunk = chunkIndex === undefined || chunkIndex === 0;
+    const cleanedContent = cleanContent(node.content);
+    const declarationOnly = extractDeclarationOnly(cleanedContent);
+    const compactContainerContext = getCompactContainerContext(cleanedContent, declarationOnly);
+    if (compactContainerContext) {
+        parts.push(compactContainerContext);
+    }
+    if (prevTail) {
+        parts.push(`[preceding context]: ...${cleanContent(prevTail)}`);
+    }
+    if (isFirstChunk && node.methodNames?.length) {
         parts.push(`Methods: ${node.methodNames.join(', ')}`);
     }
-    if (node.fieldNames?.length) {
+    if (isFirstChunk && node.fieldNames?.length) {
         parts.push(`Properties: ${node.fieldNames.join(', ')}`);
     }
-    const declarationOnly = extractDeclarationOnly(cleanContent(node.content));
-    if (declarationOnly) {
+    if (isFirstChunk && declarationOnly) {
         parts.push('', declarationOnly);
     }
     const cleanedChunk = cleanContent(codeBody);
-    if (cleanedChunk && cleanedChunk !== cleanContent(node.content)) {
+    if (cleanedChunk && cleanedChunk !== cleanedContent) {
         parts.push('', cleanedChunk);
     }
     return parts.join('\n');
@@ -179,19 +190,17 @@ export const extractDeclarationOnly = (content) => {
  * Generate embedding text for any embeddable node
  * Dispatches to the appropriate generator based on node label
  */
-export const generateEmbeddingText = (node, codeBody, config = {}) => {
+export const generateEmbeddingText = (node, codeBody, config = {}, chunkIndex, prevTail) => {
     if (isShortLabel(node.label)) {
         const header = buildMetadataHeader(node, config);
         const cleaned = cleanContent(node.content);
         return `${header}\n\n${cleaned}`;
     }
-    if (node.label === 'Class') {
-        return generateClassText(node, codeBody, config);
-    }
-    if (node.label === 'Interface') {
-        return generateStructuralTypeText(node, codeBody, config);
+    const chunkingRule = CHUNKING_RULES[node.label];
+    if (chunkingRule?.structuralTextMode === STRUCTURAL_TEXT_MODE_DECLARATION) {
+        return generateStructuralTypeText(node, codeBody, config, chunkIndex, prevTail);
     }
-    return generateCodeBodyText(node, codeBody, config);
+    return generateCodeBodyText(node, codeBody, config, prevTail);
 };
 /**
  * Export truncation helper for testing

package/dist/core/embeddings/types.d.ts

@@ -3,6 +3,38 @@
  *
  * Type definitions for the embedding generation and semantic search system.
  */
+export declare const LABEL_FUNCTION: "Function";
+export declare const LABEL_METHOD: "Method";
+export declare const LABEL_CONSTRUCTOR: "Constructor";
+export declare const LABEL_CLASS: "Class";
+export declare const LABEL_INTERFACE: "Interface";
+export declare const LABEL_STRUCT: "Struct";
+export declare const LABEL_ENUM: "Enum";
+export declare const LABEL_TRAIT: "Trait";
+export declare const LABEL_IMPL: "Impl";
+export declare const LABEL_MACRO: "Macro";
+export declare const LABEL_NAMESPACE: "Namespace";
+export declare const LABEL_TYPE_ALIAS: "TypeAlias";
+export declare const LABEL_TYPEDEF: "Typedef";
+export declare const LABEL_CONST: "Const";
+export declare const LABEL_PROPERTY: "Property";
+export declare const LABEL_RECORD: "Record";
+export declare const LABEL_UNION: "Union";
+export declare const LABEL_STATIC: "Static";
+export declare const LABEL_VARIABLE: "Variable";
+export declare const LABEL_CODE_ELEMENT: "CodeElement";
+export declare const CHUNK_MODE_AST_FUNCTION: "ast-function";
+export declare const CHUNK_MODE_AST_DECLARATION: "ast-declaration";
+export declare const CHUNK_MODE_CHARACTER: "character";
+export declare const STRUCTURAL_TEXT_MODE_NONE: "none";
+export declare const STRUCTURAL_TEXT_MODE_DECLARATION: "declaration";
+export interface ChunkingRule {
+    mode: typeof CHUNK_MODE_AST_FUNCTION | typeof CHUNK_MODE_AST_DECLARATION | typeof CHUNK_MODE_CHARACTER;
+    includePrefix: boolean;
+    includeSuffix: boolean;
+    groupFields: boolean;
+    structuralTextMode: typeof STRUCTURAL_TEXT_MODE_NONE | typeof STRUCTURAL_TEXT_MODE_DECLARATION;
+}
 /**
  * Node labels that need chunking (have code body, potentially long)
  */
@@ -29,13 +61,22 @@ export declare const isChunkableLabel: (label: string) => boolean;
  */
 export declare const isShortLabel: (label: string) => boolean;
 /**
- * Node labels that have structural names (methods/fields) extractable via AST
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
  */
 export declare const STRUCTURAL_LABELS: ReadonlySet<string>;
 /**
  * Node labels that have isExported column in their schema
  */
 export declare const LABELS_WITH_EXPORTED: ReadonlySet<string>;
+/**
+ * Labels that need special chunking and/or structural text semantics.
+ * Any chunkable label omitted here intentionally falls back to characterChunk
+ * plus generateCodeBodyText (for example Enum/Trait/Impl/Macro/Namespace).
+ */
+type ChunkableLabel = (typeof CHUNKABLE_LABELS)[number];
+export declare const CHUNKING_RULES: Readonly<Partial<Record<ChunkableLabel, ChunkingRule>>>;
 /**
  * Embedding pipeline phases
  */
@@ -163,3 +204,4 @@ export declare const dedupBestChunks: (rows: ChunkSearchRow[], limit?: number) =
  * or can tell the result set is exhausted.
  */
 export declare const collectBestChunks: (limit: number, fetchRows: (fetchLimit: number) => Promise<ChunkSearchRow[]>, maxFetch?: number) => Promise<Map<string, BestChunkMatch>>;
+export {};

package/dist/core/embeddings/types.js

@@ -3,34 +3,61 @@
  *
  * Type definitions for the embedding generation and semantic search system.
  */
+export const LABEL_FUNCTION = 'Function';
+export const LABEL_METHOD = 'Method';
+export const LABEL_CONSTRUCTOR = 'Constructor';
+export const LABEL_CLASS = 'Class';
+export const LABEL_INTERFACE = 'Interface';
+export const LABEL_STRUCT = 'Struct';
+export const LABEL_ENUM = 'Enum';
+export const LABEL_TRAIT = 'Trait';
+export const LABEL_IMPL = 'Impl';
+export const LABEL_MACRO = 'Macro';
+export const LABEL_NAMESPACE = 'Namespace';
+export const LABEL_TYPE_ALIAS = 'TypeAlias';
+export const LABEL_TYPEDEF = 'Typedef';
+export const LABEL_CONST = 'Const';
+export const LABEL_PROPERTY = 'Property';
+export const LABEL_RECORD = 'Record';
+export const LABEL_UNION = 'Union';
+export const LABEL_STATIC = 'Static';
+export const LABEL_VARIABLE = 'Variable';
+export const LABEL_CODE_ELEMENT = 'CodeElement';
+export const CHUNK_MODE_AST_FUNCTION = 'ast-function';
+export const CHUNK_MODE_AST_DECLARATION = 'ast-declaration';
+// CHUNK_MODE_CHARACTER exists for type completeness but is a no-op in CHUNKING_RULES —
+// omit the entry entirely to get character fallback via chunker.ts dispatch.
+export const CHUNK_MODE_CHARACTER = 'character';
+export const STRUCTURAL_TEXT_MODE_NONE = 'none';
+export const STRUCTURAL_TEXT_MODE_DECLARATION = 'declaration';
 /**
  * Node labels that need chunking (have code body, potentially long)
  */
 export const CHUNKABLE_LABELS = [
-    'Function',
-    'Method',
-    'Constructor',
-    'Class',
-    'Interface',
-    'Struct',
-    'Enum',
-    'Trait',
-    'Impl',
-    'Macro',
-    'Namespace',
+    LABEL_FUNCTION,
+    LABEL_METHOD,
+    LABEL_CONSTRUCTOR,
+    LABEL_CLASS,
+    LABEL_INTERFACE,
+    LABEL_STRUCT,
+    LABEL_ENUM,
+    LABEL_TRAIT,
+    LABEL_IMPL,
+    LABEL_MACRO,
+    LABEL_NAMESPACE,
 ];
 /**
  * Node labels that are short (no chunking needed, embed directly)
  */
 export const SHORT_LABELS = [
-    'TypeAlias',
-    'Typedef',
-    'Const',
-    'Property',
-    'Record',
-    'Union',
-    'Static',
-    'Variable',
+    LABEL_TYPE_ALIAS,
+    LABEL_TYPEDEF,
+    LABEL_CONST,
+    LABEL_PROPERTY,
+    LABEL_RECORD,
+    LABEL_UNION,
+    LABEL_STATIC,
+    LABEL_VARIABLE,
 ];
 /**
  * All embeddable labels (union of CHUNKABLE + SHORT)
@@ -49,24 +76,69 @@ export const isChunkableLabel = (label) => CHUNKABLE_LABELS.includes(label);
  */
 export const isShortLabel = (label) => SHORT_LABELS.includes(label);
 /**
- * Node labels that have structural names (methods/fields) extractable via AST
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
  */
 export const STRUCTURAL_LABELS = new Set([
-    'Class',
-    'Struct',
-    'Interface',
-    'Enum',
+    LABEL_CLASS,
+    LABEL_STRUCT,
+    LABEL_INTERFACE,
 ]);
 /**
  * Node labels that have isExported column in their schema
  */
 export const LABELS_WITH_EXPORTED = new Set([
-    'Function',
-    'Class',
-    'Interface',
-    'Method',
-    'CodeElement',
+    LABEL_FUNCTION,
+    LABEL_CLASS,
+    LABEL_INTERFACE,
+    LABEL_METHOD,
+    LABEL_CODE_ELEMENT,
 ]);
+export const CHUNKING_RULES = {
+    [LABEL_FUNCTION]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_METHOD]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CONSTRUCTOR]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CLASS]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+    [LABEL_INTERFACE]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+    [LABEL_STRUCT]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+};
 /**
  * Default embedding configuration
  * Uses snowflake-arctic-embed-xs for browser efficiency