Refactoring: Mention Handling: A Modular Approach for Enhanced Maintainability

[Menes1337]

What problem does this proposed feature solve?

The current implementation of mentions lacks a centralized and easily extensible mechanism for adding context to each provider (LLM) call. This poses several challenges:

• Token Usage Optimization: Without a clear structure, optimizing token usage across different mention types becomes difficult and inconsistent.

• Feature Extensibility: Adding new mention types or modifying existing ones requires significant code changes in multiple places, increasing the risk of errors and regressions.

• Maintainability: The lack of a unified approach makes the codebase harder to understand, maintain, and debug.

Describe the proposed solution in detail

The proposed solution focuses on consolidating and streamlining the implementation of mentions to address the problems outlined above. By introducing a clear separation of concerns and a well-defined interface for mention handlers, we can achieve the following:

• Improved Context Management: The proposed architecture allows for more granular control over the context added to each LLM call, enabling better token usage optimization.
• Simplified Extensibility: Adding new mention types becomes a straightforward process of implementing the MentionHandler interface and registering the new handler.
• Enhanced Maintainability: The centralized structure and clear separation of concerns make the codebase easier to understand, maintain, and test.
• Increased Testability: The well-defined interface for mention handlers facilitates unit testing and integration testing, ensuring the quality and reliability of the mentions feature.
• Reduced Code Duplication: By abstracting common logic into base classes or utility functions, we can minimize code duplication and improve code reuse.
• Clearer Code Structure: The diagram illustrates a more organized and intuitive code structure, making it easier for developers to navigate and understand the codebase.

Technical considerations or implementation details (optional)

No response

Describe alternatives considered (if any)

No response

Additional Context & Mockups

classDiagram
    direction LR

    class MentionHandler {
        <<interface>>
        mentionType: MentionType
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
        openMention(mention: string): Promise<void>
    }

    class BrowserMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        +BrowserMentionHandler(urlContentFetcher?: UrlContentFetcher)
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- BrowserMentionHandler

    class FileMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        +FileMentionHandler(cwd: string, fileContextTracker?: FileContextTracker)
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
        getFileContent(mentionPath: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- FileMentionHandler

    class FolderMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        +FolderMentionHandler(cwd: string)
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
        getFolderContent(mentionPath: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- FolderMentionHandler

    class GitChangesMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- GitChangesMentionHandler

    class GitCommitMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- GitCommitMentionHandler

    class ProblemsMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- ProblemsMentionHandler

    class TerminalMentionHandler {
        static mentionType: MentionType
        mentionType: MentionType
        static identifyMention(mention: string): boolean
        openMention(mention: string): Promise<void>
        replaceMention(mention: string): string
        addContext(mention: string, cwd: string): Promise<string>
    }

    MentionHandler <|-- TerminalMentionHandler

    class MentionType {
        <<enumeration>>
        Problems
        File
        Folder
        Browser
        GitChanges
        GitCommit
        Terminal
        None
    }

    class UserMention {
        mention: string
        mentionHandler: MentionHandler
        +UserMention(mention: string, mentionHandler: MentionHandler)
    }

    class index {
        +openMention(mention?: string): Promise<void>
        -getMentionType(mention: string): MentionType | null
        -instantiateMentionHandler(mentionType: MentionType, cwd: string, urlContentFetcher?: UrlContentFetcher, fileContextTracker?: FileContextTracker): MentionHandler | null
        +parseMentions(text: string, cwd: string, urlContentFetcher: UrlContentFetcher, fileContextTracker?: FileContextTracker): Promise<string>
    }

    UserMention -- MentionHandler : has a
    index -- UserMention : uses

Loading

Proposal Checklist

• I have searched existing Issues and Discussions to ensure this proposal is not a duplicate.
• This proposal is for a specific, actionable change intended for implementation (not a general idea).
• I understand that this proposal requires review and approval before any development work begins.

Are you interested in implementing this feature if approved?

• Yes, I would like to contribute to implementing this feature.

[hannesrudolph]

@Menes1337 What specifically about the current implementation lacks centralized structure? Are there examples of where it breaks down in practice or where extensibility has caused issues? Curious what concrete pain points you’re basing this on.

[Menes1337]

@hannesrudolph The current implementation has several structural issues:

Scattered Logic: Mention handling is distributed across multiple files with no consistent pattern, making it hard to follow the complete flow
Code Duplication: Each mention type reimplemented similar identification logic, violating DRY principles. For example, each type needed its own ad-hoc recognition code rather than using a consistent pattern like the identifyMention static method I've proposed for each type.
No Interface Consistency: Mention types are handled with inconsistent patterns, making maintenance difficult and error-prone.
Direct Coupling: The logic for processing mentions is directly coupled with application code, creating tight dependencies.

My solution addresses these with:

Unified Interface: I will create a clear MentionHandler interface that standardizes how all mention types are processed through consistent methods (replaceMention, addContext, openMention).
Modular Implementation: Each mention type has its own handler class that implements this interface, making it easy to understand and extend.
Static Recognition Methods: Each handler has a standardized identifyMention method that follows the same pattern, removing duplicated identification logic.
Centralized Processing: The new parseMentions function will create a common pipeline for all mention types.
Real-world benefits: Adding a new MentionHandler requires only implementing a new handler class without modifying existing code. Testing became more straightforward with clear boundaries.

Once this refactoring is done I would like to focus on bringing new mentions on top of it or refactor existing ones to improve context handling. This is my main goal - but as always clean up before moving forward.

[hannesrudolph]

So your proposal is a complete refactor?

[Menes1337]

@hannesrudolph For this Code section mentioned - yes. I am currently prototyping „Support for Symbols“ (Classes, methods etc.)

Frontend(Webview) has even more the need for refactoring but one thing at a time.

[hannesrudolph]

@Menes1337 I think we are currently working on this piecemeal. @mrubens What do you think of this? Should we put together a more detailed implementation for one section at a time and then allow contributors to take it one one piece at a time?