byterover-cli 1.8.0 → 2.1.0

package/dist/agent/infra/tools/implementations/memory-symbol-tree.js

@@ -0,0 +1,283 @@
+import { CONTEXT_FILE } from '../../../../server/constants.js';
+import { parseRelations } from '../../../../server/core/domain/knowledge/relation-parser.js';
+/**
+ * Symbol kinds in the memory hierarchy, ordered by depth.
+ * Mirrors Serena's SymbolKind pattern for code symbols.
+ */
+export var MemorySymbolKind;
+(function (MemorySymbolKind) {
+    MemorySymbolKind[MemorySymbolKind["Context"] = 4] = "Context";
+    MemorySymbolKind[MemorySymbolKind["Domain"] = 1] = "Domain";
+    MemorySymbolKind[MemorySymbolKind["Subtopic"] = 3] = "Subtopic";
+    MemorySymbolKind[MemorySymbolKind["Summary"] = 5] = "Summary";
+    MemorySymbolKind[MemorySymbolKind["Topic"] = 2] = "Topic";
+})(MemorySymbolKind || (MemorySymbolKind = {}));
+const SYMBOL_KIND_LABELS = {
+    [MemorySymbolKind.Context]: 'context',
+    [MemorySymbolKind.Domain]: 'domain',
+    [MemorySymbolKind.Subtopic]: 'subtopic',
+    [MemorySymbolKind.Summary]: 'summary',
+    [MemorySymbolKind.Topic]: 'topic',
+};
+const DEFAULT_METADATA = {
+    importance: 50,
+    keywords: [],
+    maturity: 'draft',
+    tags: [],
+};
+/**
+ * Determine the MemorySymbolKind based on path depth and whether it's a context.md file.
+ * Path structure: domain/topic/file.md or domain/topic/subtopic/file.md
+ */
+function determineKind(segments) {
+    switch (segments.length) {
+        case 1: {
+            return MemorySymbolKind.Domain;
+        }
+        case 2: {
+            return MemorySymbolKind.Topic;
+        }
+        case 3: {
+            return MemorySymbolKind.Subtopic;
+        }
+        default: {
+            // 4+ segments: treat deepest folder as subtopic-level
+            return MemorySymbolKind.Subtopic;
+        }
+    }
+}
+function extractMetadataFromScoring(scoring) {
+    return {
+        importance: scoring.importance ?? 50,
+        keywords: [],
+        maturity: scoring.maturity ?? 'draft',
+        tags: [],
+    };
+}
+/**
+ * Get or create a folder symbol (Domain/Topic/Subtopic) at the given path.
+ * Creates intermediate nodes as needed.
+ */
+function getOrCreateFolderNode(symbolMap, root, folderPath, folderSegments) {
+    const existing = symbolMap.get(folderPath);
+    if (existing) {
+        return existing;
+    }
+    // Ensure parent exists first (recursive)
+    let parentNode;
+    if (folderSegments.length > 1) {
+        const parentSegments = folderSegments.slice(0, -1);
+        const parentPath = parentSegments.join('/');
+        parentNode = getOrCreateFolderNode(symbolMap, root, parentPath, parentSegments);
+    }
+    const kind = determineKind(folderSegments);
+    const node = {
+        children: [],
+        kind,
+        metadata: { ...DEFAULT_METADATA },
+        name: folderSegments.at(-1),
+        parent: parentNode,
+        path: folderPath,
+    };
+    symbolMap.set(folderPath, node);
+    if (parentNode) {
+        parentNode.children.push(node);
+    }
+    else {
+        // Top-level domain
+        root.push(node);
+    }
+    return node;
+}
+/**
+ * Build a symbol tree from the indexed document map.
+ * No filesystem I/O — operates entirely on the already-loaded documents.
+ *
+ * context.md files are absorbed into their parent folder node (enriching its metadata)
+ * rather than being treated as leaf Context nodes.
+ *
+ * @param documentMap - Indexed documents (excludes _index.md, includes stubs)
+ * @param summaryMap - Optional map of _index.md summary documents for folder annotation
+ */
+export function buildSymbolTree(documentMap, summaryMap) {
+    const root = [];
+    const symbolMap = new Map();
+    // First pass: collect all documents, create folder nodes, identify context.md files
+    const contextFiles = [];
+    const leafDocuments = [];
+    for (const doc of documentMap.values()) {
+        const segments = doc.path.split('/');
+        const fileName = segments.at(-1);
+        if (fileName === CONTEXT_FILE) {
+            contextFiles.push(doc);
+        }
+        else {
+            leafDocuments.push(doc);
+        }
+    }
+    // Second pass: create folder nodes for all unique directory paths
+    const allFolderPaths = new Set();
+    for (const doc of documentMap.values()) {
+        const segments = doc.path.split('/');
+        // Collect all ancestor folder paths
+        for (let i = 1; i < segments.length; i++) {
+            allFolderPaths.add(segments.slice(0, i).join('/'));
+        }
+    }
+    for (const folderPath of allFolderPaths) {
+        const folderSegments = folderPath.split('/');
+        getOrCreateFolderNode(symbolMap, root, folderPath, folderSegments);
+    }
+    // Third pass: absorb context.md files into their parent folder nodes
+    for (const doc of contextFiles) {
+        const segments = doc.path.split('/');
+        const folderPath = segments.slice(0, -1).join('/');
+        const folderNode = symbolMap.get(folderPath);
+        if (folderNode) {
+            folderNode.metadata = {
+                ...folderNode.metadata,
+                ...extractMetadataFromScoring(doc.scoring),
+            };
+        }
+        // Also register the context.md path itself for direct lookups
+        symbolMap.set(doc.path, folderNode ?? getOrCreateFolderNode(symbolMap, root, folderPath, segments.slice(0, -1)));
+    }
+    // Fourth pass: create leaf Context nodes for non-context.md documents
+    for (const doc of leafDocuments) {
+        const segments = doc.path.split('/');
+        const folderPath = segments.slice(0, -1).join('/');
+        const parentNode = symbolMap.get(folderPath);
+        const contextNode = {
+            children: [],
+            kind: MemorySymbolKind.Context,
+            metadata: extractMetadataFromScoring(doc.scoring),
+            name: doc.title || segments.at(-1).replace(/\.md$/, ''),
+            parent: parentNode,
+            path: doc.path,
+        };
+        symbolMap.set(doc.path, contextNode);
+        if (parentNode) {
+            parentNode.children.push(contextNode);
+        }
+    }
+    // Fifth pass: attach summary info from _index.md files to their parent folder nodes
+    if (summaryMap) {
+        for (const summary of summaryMap.values()) {
+            const segments = summary.path.split('/');
+            const folderPath = segments.slice(0, -1).join('/');
+            const folderNode = symbolMap.get(folderPath);
+            if (folderNode) {
+                folderNode.summaryInfo = {
+                    condensationOrder: summary.condensationOrder,
+                    tokenCount: summary.tokenCount,
+                };
+            }
+        }
+    }
+    // Sort root domains and all children alphabetically
+    sortSymbolChildren(root);
+    return { root, symbolMap };
+}
+function sortSymbolChildren(symbols) {
+    symbols.sort((a, b) => a.name.localeCompare(b.name));
+    for (const symbol of symbols) {
+        if (symbol.children.length > 0) {
+            sortSymbolChildren(symbol.children);
+        }
+    }
+}
+/**
+ * Get a structural overview of the symbol tree at configurable depth.
+ *
+ * @param tree - The memory symbol tree
+ * @param path - Optional path to scope the overview (e.g. "auth" for auth domain only)
+ * @param depth - Max depth to traverse (default 2: domains + topics)
+ */
+export function getSymbolOverview(tree, path, depth = 2) {
+    const entries = [];
+    let startNodes;
+    if (path) {
+        const node = tree.symbolMap.get(path);
+        if (!node) {
+            return [];
+        }
+        startNodes = [node];
+    }
+    else {
+        startNodes = tree.root;
+    }
+    function traverse(symbols, currentDepth) {
+        for (const symbol of symbols) {
+            const entry = {
+                childCount: symbol.children.length,
+                importance: symbol.metadata.importance,
+                kind: SYMBOL_KIND_LABELS[symbol.kind] ?? 'unknown',
+                maturity: symbol.metadata.maturity,
+                name: symbol.name,
+                path: symbol.path,
+            };
+            if (symbol.summaryInfo) {
+                entry.condensationOrder = symbol.summaryInfo.condensationOrder;
+                entry.tokenCount = symbol.summaryInfo.tokenCount;
+            }
+            entries.push(entry);
+            if (currentDepth < depth && symbol.children.length > 0) {
+                traverse(symbol.children, currentDepth + 1);
+            }
+        }
+    }
+    traverse(startNodes, 1);
+    return entries;
+}
+/**
+ * Collect all leaf document IDs (Context nodes) under a given path.
+ * Used for scoped search — restricts MiniSearch to a subtree.
+ */
+export function getSubtreeDocumentIds(tree, path) {
+    const ids = new Set();
+    const node = tree.symbolMap.get(path);
+    if (!node) {
+        return ids;
+    }
+    function collect(symbol) {
+        if (symbol.kind === MemorySymbolKind.Context) {
+            ids.add(symbol.path);
+        }
+        for (const child of symbol.children) {
+            collect(child);
+        }
+    }
+    collect(node);
+    return ids;
+}
+/**
+ * Build a bidirectional reference index from @relation annotations in document content.
+ * Reuses the existing parseRelations() function from relation-parser.ts.
+ */
+export function buildReferenceIndex(documentMap) {
+    const backlinks = new Map();
+    const forwardLinks = new Map();
+    for (const doc of documentMap.values()) {
+        const relations = parseRelations(doc.content);
+        if (relations.length === 0) {
+            continue;
+        }
+        forwardLinks.set(doc.path, relations);
+        for (const target of relations) {
+            const existing = backlinks.get(target);
+            if (existing) {
+                existing.push(doc.path);
+            }
+            else {
+                backlinks.set(target, [doc.path]);
+            }
+        }
+    }
+    return { backlinks, forwardLinks };
+}
+/**
+ * Get the symbol kind label for display in search results.
+ */
+export function getSymbolKindLabel(kind) {
+    return SYMBOL_KIND_LABELS[kind] ?? 'unknown';
+}

package/dist/agent/infra/tools/implementations/search-knowledge-service.d.ts

@@ -9,6 +9,25 @@ export interface SearchKnowledgeServiceConfig {
     /** Cache TTL in milliseconds (defaults to 5000) */
     cacheTtlMs?: number;
 }
+/**
+ * Extended search options supporting symbolic filters.
+ */
+export interface SearchOptions {
+    /** Symbol kinds to exclude from results (e.g. ['subtopic']) */
+    excludeKinds?: string[];
+    /** Symbol kinds to include in results (e.g. ['domain', 'context']) */
+    includeKinds?: string[];
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Minimum maturity tier for results */
+    minMaturity?: 'core' | 'draft' | 'validated';
+    /** If true, return tree structure overview instead of search results */
+    overview?: boolean;
+    /** Depth for overview mode (default: 2) */
+    overviewDepth?: number;
+    /** Path prefix to scope search within (e.g. "auth" or "auth/jwt-tokens") */
+    scope?: string;
+}
 /**
  * SearchKnowledgeService implementation.
  * Provides knowledge search functionality with caching and indexing.
@@ -17,18 +36,42 @@ export declare class SearchKnowledgeService implements ISearchKnowledgeService {
     private readonly baseDirectory;
     private readonly cacheTtlMs;
     private readonly fileSystem;
+    private readonly pendingAccessHits;
     private readonly state;
     constructor(fileSystem: IFileSystem, config?: SearchKnowledgeServiceConfig);
+    /**
+     * Flush accumulated access hits to disk by updating frontmatter scoring.
+     * Called during index rebuild to batch writes and avoid write amplification.
+     * Best-effort: errors are swallowed per file.
+     */
+    flushAccessHits(contextTreePath: string): Promise<void>;
     /**
      * Search the knowledge base for relevant topics.
+     * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode.
      *
-     * @param query - Natural language query string
-     * @param options - Search options
-     * @returns Search results with matching topics
+     * @param query - Natural language query string or symbolic path (e.g. "auth/jwt")
+     * @param options - Search options including symbolic filters
+     * @returns Search results with matching topics, enriched with symbolic metadata
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchKnowledgeResult>;
+    private accumulateAccessHits;
+    /**
+     * Build overview result showing the tree structure at configurable depth.
+     */
+    private buildOverviewResult;
+    /**
+     * Enrich a search result with symbolic metadata and backlink info.
+     * For archive stubs, extracts points_to path into archiveFullPath.
+     */
+    private enrichResult;
+    /**
+     * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
+     */
+    private runTextSearch;
+    /**
+     * Try to resolve the query as a symbolic path. Returns null if no path match found.
      */
-    search(query: string, options?: {
-        limit?: number;
-    }): Promise<SearchKnowledgeResult>;
+    private trySymbolicSearch;
 }
 /**
  * Factory function to create a SearchKnowledgeService instance.