File/Code Context Linking with Custom Syntax

[MadTinker]

Overview

Implement a system to link todos directly to files, code snippets, and symbols using a custom markdown-like syntax.

Proposed Syntax

• Files: [[file:path/to/file.py]]
• Code Ranges: [[code:path/to/file.py#L10-L20]]
• Symbols: [[symbol:ClassName.methodName]]
• Multiple Links: Support multiple references per todo

Implementation Components

1. Storage System

• Structured metadata format for links
• Efficient querying of linked files/symbols
• Version tracking for linked code

2. Validation Engine

• Verify file paths exist at link creation
• Validate line numbers are within file bounds
• Symbol resolution and validation
• Real-time validation during editing

3. Context Preview

• Generate code snippets for linked ranges
• Show first/last 3 lines for large ranges
• Syntax highlighting in previews
• Diff view when code changes

4. Bidirectional Linking

• Comment tags in code: // TODO[todo-id]: description
• Automatic discovery of code-embedded todos
• Sync between code comments and todo system

5. Search & Discovery

• Search todos by linked files
• Find todos related to specific symbols
• Filter by file extensions or directories
• Full-text search across linked content

6. Refactoring Support

• Track file moves/renames automatically
• Update links when files are relocated
• Handle symbol renames and refactoring
• Broken link detection and reporting

7. IDE Integration

• VS Code/Cursor extension for link creation
• Quick actions to create todos from selected code
• Navigate from todo to linked code
• Hover previews for linked content

8. Advanced Features

• Code snapshot storage at todo creation
• Diff tracking to see what changed
• Git blame integration for context
• Automated link suggestions based on git history

Benefits

• Better Context: Immediate understanding of what needs to be done
• Faster Navigation: Direct links to relevant code
• Living Documentation: Todos evolve with the codebase
• Reduced Context Switching: Everything in one place

Acceptance Criteria

• Custom syntax is parsed and validated
• Links are stored efficiently and searchable
• Context previews work reliably
• Refactoring doesn't break links
• IDE integration provides smooth workflow
• Performance is acceptable for large codebases

Priority

High - Game-changing feature for developer productivity