minovative-mind-cli 2.13.5 → 2.14.1

package/dist/services/mentionEngine.d.ts

@@ -0,0 +1,385 @@
+/**
+ * @fileoverview Context Mentions and Autocomplete Engine for Minovative Mind CLI.
+ *
+ * This service provides:
+ * 1. **Autocomplete Suggestions**: Real-time suggestion generation for `@files`, `@symbols`,
+ *    `@git` context helpers, `@workspace` aliases, and `@diagnostics` / special mentions.
+ * 2. **Mention Parsing**: Robust parsing of `@mention` tokens in user prompts with support for
+ *    line ranges (`:10-50`), scoped symbol targets (`@symbol:foo`), git modifiers (`@git:diff`),
+ *    and cross-workspace references (`@alias/path`).
+ * 3. **Context Resolution**: Resolves all mentions in a prompt into structured, sanitized,
+ *    token-budgeted XML injection blocks ready for LLM consumption.
+ */
+import { SymbolKind } from '../utils/symbolExtractor.js';
+/**
+ * Types of context mentions supported by the engine.
+ */
+export type MentionType = 'file' | 'symbol' | 'git' | 'workspace' | 'diagnostics' | 'terminal';
+/**
+ * Represents a parsed `@mention` token extracted from a user prompt.
+ */
+export interface ParsedMention {
+    /** The full raw matched mention string (e.g. `@src/utils/config.ts`, `@git:diff`, `@symbol:runAgent`) */
+    raw: string;
+    /** The classified type of mention */
+    type: MentionType;
+    /** The primary target identifier (e.g. `src/utils/config.ts`, `runAgent`, `diff`, `backend`) */
+    target: string;
+    /** Optional secondary target (e.g. symbol name if format is `@symbol:file.ts:symbolName`) */
+    subTarget?: string;
+    /** Optional external workspace alias if referencing a registered external workspace */
+    workspaceAlias?: string | null;
+    /** Optional line range specified in file mention (1-indexed) */
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+    /** The 0-based character offsets [start, end] of the mention token in the original prompt */
+    range: [number, number];
+    /** Whether the mention parsed into a structurally valid format */
+    valid: boolean;
+    /** Optional parse or resolution warning */
+    error?: string;
+}
+/**
+ * An autocomplete suggestion item presented to the user during interactive typing.
+ */
+export interface MentionSuggestion {
+    /** The display label shown in autocomplete dropdown */
+    label: string;
+    /** The text inserted/replaced when this suggestion is selected */
+    value: string;
+    /** The mention classification type */
+    type: MentionType;
+    /** Optional category badge for styling (e.g. 'file', 'lines', 'sym', 'git', 'ws', 'diag', 'term') */
+    category?: 'file' | 'lines' | 'symbol' | 'sym' | 'git' | 'workspace' | 'ws' | 'diagnostics' | 'diag' | 'terminal' | 'term' | 'doc' | string;
+    /** A concise human-readable description (e.g. "Git working tree diff", "File (4.2 KB)") */
+    description: string;
+    /** Detailed metadata or subtitle */
+    detail?: string;
+    /** Descriptive helper label indicating category/parsing status */
+    helperLabel?: string;
+    /** Display icon / glyph */
+    icon?: string;
+    /** Relevance ranking score (higher is better) */
+    score?: number;
+    /** External workspace alias if applicable */
+    workspaceAlias?: string | null;
+    /** Associated file path if applicable */
+    filePath?: string;
+    /** Associated symbol kind if applicable */
+    symbolKind?: SymbolKind | string;
+}
+/**
+ * Configuration options for generating autocomplete suggestions.
+ */
+export interface MentionSuggestionOptions {
+    /** The primary workspace root directory (defaults to process.cwd()) */
+    workspaceRoot?: string;
+    /** The active search query typed after the `@` symbol */
+    query?: string;
+    /** The 0-based cursor position in the input string */
+    cursorPosition?: number;
+    /** Maximum number of suggestions to return (defaults to 25) */
+    maxSuggestions?: number;
+    /** Filter to specific mention types (e.g. only ['file', 'symbol']) */
+    includeTypes?: MentionType[];
+    /** Optional pre-computed file list to accelerate suggestion generation */
+    cachedFileList?: string[];
+    /** Maximum number of files to scan for symbols */
+    maxSymbolFiles?: number;
+}
+/**
+ * Result of resolving a single mention's contents.
+ */
+export interface ResolvedMentionContext {
+    /** The original parsed mention */
+    mention: ParsedMention;
+    /** Whether resolution succeeded without fatal errors */
+    resolved: boolean;
+    /** The structured XML context block representing the resolved content */
+    content: string;
+    /** Estimated token count of the content block */
+    tokenEstimate: number;
+    /** Error message if resolution failed */
+    error?: string;
+    /** Concise status label indicating resolution summary (e.g. "lines 10-50, 420 chars") */
+    statusLabel?: string;
+    /** Descriptive helper badge/label for status and parsing details */
+    helperLabel?: string;
+    /** Supplementary structured metadata */
+    metadata?: {
+        absolutePath?: string;
+        relativePath?: string;
+        sizeBytes?: number;
+        charCount?: number;
+        linesCount?: number;
+        totalLines?: number;
+        lineRange?: {
+            start: number;
+            end: number;
+        };
+        isSliced?: boolean;
+        workspaceAlias?: string | null;
+        symbol?: string;
+        filePath?: string;
+        kind?: string;
+        signature?: string;
+        startLine?: number;
+        endLine?: number;
+        gitSubCommand?: string;
+        contextType?: string;
+        outputLines?: number;
+        isClean?: boolean;
+        alias?: string;
+        path?: string;
+        profile?: string;
+        filesCount?: number;
+        filesChecked?: number;
+        issuesCount?: number;
+        issues?: string[];
+        platform?: string;
+        arch?: string;
+        nodeVersion?: string;
+        cwd?: string;
+        statusLabel?: string;
+        helperLabel?: string;
+        category?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Options configuring mention content resolution.
+ */
+export interface ResolveMentionsOptions {
+    /** Maximum total character budget for resolved context injection */
+    maxChars?: number;
+    /** Whether to use AST-scoped outlines for large source files */
+    useScopedOutline?: boolean;
+    /** Git command execution timeout in milliseconds (defaults to 5000) */
+    gitTimeoutMs?: number;
+    /** Maximum lines per extracted symbol definition (defaults to 300) */
+    symbolMaxLines?: number;
+}
+/**
+ * Comprehensive result of parsing and resolving all mentions in a prompt.
+ */
+export interface ResolvedMentionsResult {
+    /** The original prompt string as provided by the user */
+    originalPrompt: string;
+    /** Cleaned prompt string with mentions intact */
+    cleanedPrompt: string;
+    /** Array of individual resolved mention blocks */
+    mentions: ResolvedMentionContext[];
+    /** The unified XML context injection block `<context_mentions>...</context_mentions>` */
+    formattedContext: string;
+    /** Total estimated token count across all resolved mentions */
+    totalTokens: number;
+    /** Indicates whether any valid mentions were found and processed */
+    hasMentions: boolean;
+}
+/**
+ * Context Mentions Engine.
+ *
+ * Core engine responsible for parsing `@` tokens, providing fast autocomplete suggestions,
+ * and resolving file, symbol, git, workspace, and diagnostic mentions into structured context.
+ */
+export declare class MentionEngine {
+    /** In-memory cache for workspace file listings (TTL: 15 seconds) */
+    private fileListCache;
+    /** In-memory cache for parsed symbol indexes per file path */
+    private symbolIndexCache;
+    /** Cache TTL in milliseconds */
+    private readonly CACHE_TTL_MS;
+    /**
+     * Parses all `@mention` tokens from a user prompt text string.
+     *
+     * Correctly ignores email addresses (e.g. `user@domain.com`) and supports:
+     * - `@file:<path>` or `@<path>` (e.g. `@src/index.ts`, `@src/index.ts:10-50`)
+     * - `@symbol:<name>` or `@#<name>` or `@symbol:<filePath>:<name>`
+     * - `@git:diff`, `@git:staged`, `@git:branch`, `@git:log`, `@git:status`, `@diff`
+     * - `@<alias>` or `@<alias>/<path>` for registered external workspaces
+     * - `@diagnostics`, `@problems`, `@errors`
+     *
+     * @param prompt - The input prompt text.
+     * @param workspaceRoot - Optional workspace root for alias and file disambiguation.
+     * @returns Array of ParsedMention objects.
+     */
+    parseMentions(prompt: string, workspaceRoot?: string): ParsedMention[];
+    /**
+     * Classifies a raw mention token into its appropriate MentionType and targets.
+     *
+     * @private
+     */
+    private classifyMentionToken;
+    /**
+     * Extracts line range numbers from a path string (e.g. `src/index.ts:10-50` or `src/index.ts#10-50` or `src/index.ts:25`).
+     *
+     * @private
+     */
+    private parseLineRange;
+    /**
+     * Determines the active mention query at a specific cursor position in an input string.
+     *
+     * @param input - The current input text.
+     * @param cursorPosition - The 0-based cursor offset.
+     * @returns Object describing the active mention query and range.
+     */
+    getActiveMentionQuery(input: string, cursorPosition: number): {
+        query: string;
+        startIndex: number;
+        endIndex: number;
+        isMention: boolean;
+    };
+    /**
+     * Generates ranked autocomplete suggestions based on the current prompt text and cursor position.
+     *
+     * @param input - Full prompt input text.
+     * @param cursorPosition - Cursor index.
+     * @param options - Suggestion configuration options.
+     * @returns Array of ranked MentionSuggestion objects.
+     */
+    getSuggestions(input: string, cursorPosition: number, options?: Partial<MentionSuggestionOptions>): Promise<MentionSuggestion[]>;
+    /**
+     * Generates autocomplete suggestions for a given raw query string (the text after '@').
+     *
+     * @param query - The query string typed after '@'.
+     * @param options - Configuration options.
+     * @returns Array of ranked MentionSuggestion objects.
+     */
+    getSuggestionsForQuery(query?: string, options?: Partial<MentionSuggestionOptions>): Promise<MentionSuggestion[]>;
+    /**
+     * Generates built-in git, diagnostics, terminal, and symbol template suggestions.
+     *
+     * @private
+     */
+    private getSpecialSuggestions;
+    /**
+     * Generates registered workspace alias suggestions.
+     *
+     * @private
+     */
+    private getWorkspaceSuggestions;
+    /**
+     * Generates workspace file suggestions with fast fuzzy/prefix matching.
+     *
+     * @private
+     */
+    private getFileSuggestions;
+    /**
+     * Generates symbol suggestions across indexed source files.
+     *
+     * @private
+     */
+    private getSymbolSuggestions;
+    /**
+     * Calculates a match score between a user query and candidate keywords.
+     * Higher scores represent stronger matches.
+     *
+     * @private
+     */
+    private calculateMatchScore;
+    /**
+     * Returns a cached recursive list of all relative file paths in the workspace.
+     *
+     * @param workspaceRoot - Root directory path.
+     * @param maxFiles - Safety ceiling on maximum files returned (defaults to 3000).
+     * @returns Array of relative file paths.
+     */
+    getFileList(workspaceRoot: string, maxFiles?: number): Promise<string[]>;
+    /**
+     * Extracts and returns all declared symbols across workspace source files.
+     *
+     * @param workspaceRoot - Workspace root path.
+     * @param maxFiles - Maximum source files to scan.
+     * @returns Array of symbol entries.
+     */
+    getSymbolIndex(workspaceRoot: string, maxFiles?: number): Promise<Array<{
+        symbol: string;
+        kind?: SymbolKind;
+        filePath: string;
+        signature?: string;
+        startLine: number;
+        endLine: number;
+    }>>;
+    /**
+     * Resolves all mentions in a prompt string into structured context injection blocks.
+     *
+     * @param prompt - The user prompt containing `@mentions`.
+     * @param workspaceRoot - The primary workspace root path.
+     * @param options - Resolution and token budgeting options.
+     * @returns Comprehensive ResolvedMentionsResult containing structured XML blocks.
+     */
+    resolveMentions(prompt: string, workspaceRoot?: string, options?: ResolveMentionsOptions): Promise<ResolvedMentionsResult>;
+    /**
+     * Resolves a single parsed mention into its structured XML context block.
+     *
+     * @private
+     */
+    private resolveSingleMention;
+    /**
+     * Resolves a file mention (`@file:src/index.ts` or `@src/index.ts:10-50`).
+     *
+     * @private
+     */
+    private resolveFileMention;
+    /**
+     * Resolves a symbol mention (`@symbol:extractSymbols` or `@#extractSymbols`).
+     *
+     * @private
+     */
+    private resolveSymbolMention;
+    /**
+     * Resolves a git mention (`@git:diff`, `@git:staged`, `@git:branch`, `@git:log`, `@git:status`, `@diff`).
+     *
+     * @private
+     */
+    private resolveGitMention;
+    /**
+     * Resolves a registered workspace alias mention (`@effortlist-ai`).
+     *
+     * @private
+     */
+    private resolveWorkspaceMention;
+    /**
+     * Resolves diagnostics / problems mention (`@diagnostics`, `@problems`, `@errors`).
+     *
+     * @private
+     */
+    private resolveDiagnosticsMention;
+    /**
+     * Resolves terminal / console mention (`@terminal`, `@console`).
+     *
+     * @private
+     */
+    private resolveTerminalMention;
+    /**
+     * Formats resolved mention blocks into a unified XML context injection string,
+     * respecting character budget limits.
+     *
+     * @param resolvedMentions - Array of resolved mention blocks.
+     * @param maxChars - Optional maximum character budget.
+     * @returns Unified XML context block.
+     */
+    formatMentionsContext(resolvedMentions: ResolvedMentionContext[], maxChars?: number): string;
+    /**
+     * Helper to get an icon glyph corresponding to a file extension.
+     *
+     * @private
+     */
+    private getFileIcon;
+    /**
+     * Helper to get an icon glyph corresponding to a symbol kind.
+     *
+     * @private
+     */
+    private getSymbolIcon;
+    /**
+     * Clears in-memory caches for file listings and symbols.
+     */
+    clearCaches(): void;
+}
+/**
+ * Singleton instance of the MentionEngine.
+ */
+export declare const mentionEngine: MentionEngine;