gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/config/ignore-service.js

@@ -245,16 +245,20 @@ const IGNORED_FILES = new Set([
     '.env.test',
     '.env.example',
 ]);
-// NOTE: Negation patterns in .gitnexusignore (e.g. `!vendor/`) cannot override
-// entries in DEFAULT_IGNORE_LIST — this is intentional. The hardcoded list protects
-// against indexing directories that are almost never source code (node_modules, .git, etc.).
-// Users who need to include such directories should remove them from the hardcoded list.
+// The hardcoded DEFAULT_IGNORE_LIST is the "safety net" default: directories
+// that are almost never source code (node_modules, .git, dist, __tests__,
+// etc.). Users who legitimately need to index one of these can negate the
+// hardcoded rule via a `!pattern` line in `.gitnexusignore` (#771) — same
+// semantics as `.gitignore` negation. That override is applied in
+// `createIgnoreFilter` below; `shouldIgnorePath` itself stays a pure
+// hardcoded-list check so its callers (wiki generator, tests) get
+// deterministic results independent of per-repo config.
 export const shouldIgnorePath = (filePath) => {
     const normalizedPath = filePath.replace(/\\/g, '/');
     const parts = normalizedPath.split('/');
     const fileName = parts[parts.length - 1];
     const fileNameLower = fileName.toLowerCase();
-    // Check if any path segment is in ignore list
+    // Check if any path segment is in the hardcoded ignore list.
     for (const part of parts) {
         if (DEFAULT_IGNORE_LIST.has(part)) {
             return true;
@@ -320,6 +324,44 @@ export const loadIgnoreRules = async (repoPath, options) => {
     }
     return hasRules ? ig : null;
 };
+/**
+ * Walk ancestor segments of `rel` and check whether `.gitnexusignore`
+ * (or `.gitignore`) contains an explicit `!pattern` negation that
+ * applies. Returns true as soon as any segment — or the path itself —
+ * is matched by a negation rule.
+ *
+ * Why this exists (#771): the hardcoded DEFAULT_IGNORE_LIST would
+ * otherwise block indexing of directories like `__tests__/` even when
+ * the user has an explicit `!__tests__/` line in `.gitnexusignore`.
+ * Mirroring `.gitignore` negation semantics: a user's explicit
+ * unignore of a parent directory implicitly unignores everything
+ * underneath, so we walk the ancestor chain rather than only testing
+ * the leaf.
+ *
+ * The `ignore` package's `test(path)` returns `{ignored, unignored}`;
+ * `unignored: true` is the "a negation rule matched this path"
+ * signal. Children of a negated directory return
+ * `{ignored: false, unignored: false}` on a direct test, which is why
+ * we also walk the ancestors here.
+ */
+const hasExplicitUnignore = (ig, rel) => {
+    // Direct match on the path (as a file).
+    if (ig.test(rel).unignored)
+        return true;
+    // Direct match on the path treated as a directory — `!dir/` matches
+    // here when rel is the directory itself.
+    if (ig.test(rel + '/').unignored)
+        return true;
+    // Walk ancestor segments. `!parent/` should propagate to every
+    // descendant the same way `.gitignore` negation propagates.
+    const parts = rel.split('/');
+    for (let i = parts.length - 1; i > 0; i--) {
+        const ancestor = parts.slice(0, i).join('/') + '/';
+        if (ig.test(ancestor).unignored)
+            return true;
+    }
+    return false;
+};
 /**
  * Create a glob-compatible ignore filter combining:
  * - .gitignore / .gitnexusignore patterns (via `ignore` package)
@@ -327,6 +369,15 @@ export const loadIgnoreRules = async (repoPath, options) => {
  *
  * Returns an IgnoreLike object for glob's `ignore` option,
  * enabling directory-level pruning during traversal.
+ *
+ * Precedence (#771): user's `.gitnexusignore` negation patterns take
+ * priority over the hardcoded list, matching `.gitignore` semantics.
+ * An explicit `!pattern` rule unignores descendants even when they
+ * would otherwise be blocked by DEFAULT_IGNORE_LIST — UNLESS a more
+ * specific rule in the same file re-ignores a subset (e.g.
+ * `!__tests__/` paired with `__tests__/generated/` blocks the child
+ * while leaving the parent negated). Last-match-wins is enforced by
+ * consulting `ig.ignores(rel)` after `hasExplicitUnignore`.
  */
 export const createIgnoreFilter = async (repoPath, options) => {
     const ig = await loadIgnoreRules(repoPath, options);
@@ -337,6 +388,15 @@ export const createIgnoreFilter = async (repoPath, options) => {
             const rel = p.relative();
             if (!rel)
                 return false;
+            // User's .gitnexusignore negation takes precedence over hardcoded
+            // rules (#771). If any ancestor or the path itself was explicitly
+            // unignored AND no more-specific rule re-ignores this exact path,
+            // allow it through. The `!ig.ignores(rel)` guard matches
+            // .gitignore's last-match-wins semantics: `!__tests__/` followed
+            // by `__tests__/generated/` negates the parent but still blocks
+            // the re-ignored child.
+            if (ig && hasExplicitUnignore(ig, rel) && !ig.ignores(rel))
+                return false;
             // Check .gitignore / .gitnexusignore patterns
             if (ig && ig.ignores(rel))
                 return true;
@@ -344,10 +404,20 @@ export const createIgnoreFilter = async (repoPath, options) => {
             return shouldIgnorePath(rel);
         },
         childrenIgnored(p) {
-            // Fast path: check directory name against hardcoded list.
             // Note: dot-directories (.git, .vscode, etc.) are primarily excluded by
-            // glob's `dot: false` option in filesystem-walker.ts. This check is
-            // defense-in-depth — do not remove `dot: false` assuming this covers it.
+            // glob's `dot: false` option in filesystem-walker.ts. The hardcoded
+            // list check below is defense-in-depth — do not remove `dot: false`
+            // assuming this covers it.
+            const rel = p.relative();
+            // User's .gitnexusignore negation takes precedence (#771) — if the
+            // user explicitly unignored this directory or any ancestor via a
+            // !pattern rule, allow descent even if the directory name is in
+            // DEFAULT_IGNORE_LIST. The `!ig.ignores(rel + '/')` guard keeps
+            // last-match-wins: `!__tests__/` + `__tests__/generated/` still
+            // blocks descent into `__tests__/generated/`.
+            if (ig && rel && hasExplicitUnignore(ig, rel) && !ig.ignores(rel + '/'))
+                return false;
+            // Hardcoded list: block descent into well-known noise directories.
             if (DEFAULT_IGNORE_LIST.has(p.name))
                 return true;
             // Check against .gitignore / .gitnexusignore patterns.
@@ -358,11 +428,8 @@ export const createIgnoreFilter = async (repoPath, options) => {
             // Bare-name patterns (e.g. `local`) still match `local/` per gitignore spec:
             // the `ignore` package normalizes `dir` and `dir/` to match directories.
             // See: https://github.com/kaelzhang/node-ignore#2-filenames-and-dirnames
-            if (ig) {
-                const rel = p.relative();
-                if (rel && ig.ignores(rel + '/'))
-                    return true;
-            }
+            if (ig && rel && ig.ignores(rel + '/'))
+                return true;
             return false;
         },
     };

package/dist/core/embedding-mode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+export interface EmbeddingModeInput {
+    force?: boolean;
+    embeddings?: boolean;
+    dropEmbeddings?: boolean;
+}
+export interface EmbeddingMode {
+    /** True when phase 4 should run the embedding generation pipeline. */
+    shouldGenerateEmbeddings: boolean;
+    /** True when we should load the cache to re-insert vectors after rebuild without generating new ones. */
+    preserveExistingEmbeddings: boolean;
+    /** True when `--force` upgraded a default analyze into a regeneration because the repo was already embedded. */
+    forceRegenerateEmbeddings: boolean;
+    /** True when we need to load cached embeddings from the existing DB before the rebuild. */
+    shouldLoadCache: boolean;
+}
+export declare function deriveEmbeddingMode(options: EmbeddingModeInput, existingEmbeddingCount: number): EmbeddingMode;

package/dist/core/embedding-mode.js

@@ -0,0 +1,30 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+export function deriveEmbeddingMode(options, existingEmbeddingCount) {
+    const hasExisting = existingEmbeddingCount > 0;
+    const drop = !!options.dropEmbeddings;
+    const explicit = !!options.embeddings;
+    const force = !!options.force;
+    const forceRegenerateEmbeddings = force && !explicit && !drop && hasExisting;
+    const preserveExistingEmbeddings = !explicit && !drop && !forceRegenerateEmbeddings && hasExisting;
+    const shouldGenerateEmbeddings = explicit || forceRegenerateEmbeddings;
+    const shouldLoadCache = !drop && (shouldGenerateEmbeddings || preserveExistingEmbeddings);
+    return {
+        shouldGenerateEmbeddings,
+        preserveExistingEmbeddings,
+        forceRegenerateEmbeddings,
+        shouldLoadCache,
+    };
+}

package/dist/core/embeddings/ast-utils.js

@@ -55,17 +55,17 @@ const FUNCTION_LIKE_TYPES = new Set([
  * numbers don't apply.
  */
 export const findFunctionNode = (root) => {
-    if (FUNCTION_LIKE_TYPES.has(root.type))
-        return root;
-    for (let i = 0; i < root.namedChildCount; i++) {
-        const child = root.namedChild(i);
-        if (!child)
-            continue;
-        if (FUNCTION_LIKE_TYPES.has(child.type))
-            return child;
-        const found = findFunctionNode(child);
-        if (found)
-            return found;
+    // Iterative DFS — avoids stack overflow on deeply nested ASTs.
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (FUNCTION_LIKE_TYPES.has(node.type))
+            return node;
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child)
+                stack.push(child);
+        }
     }
     return null;
 };
@@ -89,17 +89,17 @@ export const findDeclarationNode = (root) => {
         'object_declaration', // Kotlin: object
         'impl_item', // Rust: impl
     ]);
-    if (CLASS_LIKE_TYPES.has(root.type))
-        return root;
-    for (let i = 0; i < root.namedChildCount; i++) {
-        const child = root.namedChild(i);
-        if (!child)
-            continue;
-        if (CLASS_LIKE_TYPES.has(child.type))
-            return child;
-        const found = findDeclarationNode(child);
-        if (found)
-            return found;
+    // Iterative DFS — avoids stack overflow on deeply nested ASTs.
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (CLASS_LIKE_TYPES.has(node.type))
+            return node;
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child)
+                stack.push(child);
+        }
     }
     return null;
 };

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 {};