Review Lens

Overview

This VS Code extension helps developers systematically explore and understand new codebases by enabling them to mark code as reviewed, visually tracking progress, and highlighting reviewed lines.

Core Functionality

Multiple Highlighters

The extension supports multiple highlighters, each with its own color:

• Users can define up to 5 different highlighters with custom colors
• Each highlighter can be used to mark different types of lines (e.g., "Reviewed", "Needs Review", "In Progress")
• Default highlighters include:
  • Reviewed (green)
  • Needs Review (orange)
  • In Progress (blue)
  • Blocked (red)
  • Question (purple)

Marking Lines as Reviewed

• Users can explicitly mark individual lines or selections of lines with any highlighter
• Lines marked with a highlighter will display:
  • Semi-transparent highlighting in the highlighter's color
  • Corresponding gutter icon
  • Whole-line highlighting
• Right-click on any file in the explorer to mark the entire file as reviewed
• Right-click on any folder to mark all files in that folder (and subfolders) as reviewed
• Binary files (images, PDFs, etc.) are supported with a simple reviewed/not-reviewed status
  • Binary files are detected automatically by extension or content analysis
  • When marked as reviewed, binary files show a checkmark (✓) without line-by-line tracking
  • Right-click on binary files and select "Mark File as Reviewed" to mark them

Persistence

• Highlight marks persist between VS Code sessions
• Persistence is managed via a portable JSON file stored within the project directory (.vscode/reviewed-lines.json)
• Structure of the JSON:

  {
    "filePath": {
      "hash": "file-content-hash",
      "highlights": {
        "highlighterId": [lineNumbers]
      },
      "isBinary": true|undefined
    }
  }
  

• All paths are stored as relative paths for better portability

Visual Indicators

Progress Bar

• Display progress bars in VS Code's status bar indicating:
  • Current highlighter name
  • Review coverage of the current file (highlighted lines vs. total lines)
  • Review coverage of the entire project (excluding ignored files/directories)
• Metrics calculated based on highlighted lines versus total non-ignored lines

File Explorer Integration

• Files in the VS Code file explorer show visual indicators of review coverage:
  • Checkmark (✓) for 100% reviewed files
  • Percentage (0-99%) for partially reviewed files
• Directories show review status:
  • Checkmark (✓) for directories where all files are reviewed
  • No indicator for partially reviewed directories
• Ignored files and directories (based on ignore patterns) automatically show checkmarks

Commands

Core Commands

• Toggle Review Highlight – Toggles highlighted/unhighlighted state of the current line or selection using the current highlighter
• Select Highlighter – Opens a quick pick menu to select which highlighter to use
• Undo Last Review Highlight – Undoes the most recent highlight action
• Refresh File Decorations - Manually refreshes the file explorer visual indicators if they're not appearing automatically

Highlighter Commands

• Set Highlighter: Reviewed – Sets the current highlighter to "Reviewed" (green)
• Set Highlighter: Needs Review – Sets the current highlighter to "Needs Review" (orange)
• Set Highlighter: In Progress – Sets the current highlighter to "In Progress" (blue)
• Set Highlighter: Blocked – Sets the current highlighter to "Blocked" (red)
• Set Highlighter: Question – Sets the current highlighter to "Question" (purple)

Keybindings

You can set up keybindings for the highlighter commands in your VS Code settings. Here's a suggested configuration:

{
  "keybindings": [
    {
      "command": "review-lens.setHighlighterReviewed",
      "key": "ctrl+shift+1",
      "mac": "cmd+shift+1"
    },
    {
      "command": "review-lens.setHighlighterNeedsReview",
      "key": "ctrl+shift+2",
      "mac": "cmd+shift+2"
    },
    {
      "command": "review-lens.setHighlighterInProgress",
      "key": "ctrl+shift+3",
      "mac": "cmd+shift+3"
    },
    {
      "command": "review-lens.setHighlighterBlocked",
      "key": "ctrl+shift+4",
      "mac": "cmd+shift+4"
    },
    {
      "command": "review-lens.setHighlighterQuestion",
      "key": "ctrl+shift+5",
      "mac": "cmd+shift+5"
    }
  ]
}

To set up these keybindings:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Preferences: Open Keyboard Shortcuts (JSON)"
3. Add the keybindings to your keybindings.json file

Customization Settings

Highlighter Configuration

Users can customize highlighters in VS Code settings:

"reviewLens.highlighters": [
  {
    "id": "reviewed",
    "name": "Reviewed",
    "color": "#00aa0020"
  },
  {
    "id": "needs-review",
    "name": "Needs Review",
    "color": "#ff990020"
  },
  {
    "id": "in-progress",
    "name": "In Progress",
    "color": "#0077cc20"
  },
  {
    "id": "blocked",
    "name": "Blocked",
    "color": "#cc000020"
  },
  {
    "id": "question",
    "name": "Question",
    "color": "#aa00aa20"
  }
]

Visual Display Settings

• reviewLens.showGutterIcons: Toggle display of gutter icons next to highlighted lines (default: true)
• reviewLens.showLineHighlights: Toggle display of background colors on highlighted lines (default: true)
• reviewLens.enableDirectoryCoverage: Enable or disable directory coverage calculations, which can improve performance in large projects (default: true)
• reviewLens.resetReviewedLinesOnSave: Controls whether saving changes to a file resets the reviewed lines for that file (default: true)
  • When enabled (default), reviewed lines are cleared when a file is saved with changes
  • When disabled, reviewed lines persist even when the file content changes

Ignore Patterns

• reviewLens.ignorePatterns: List of patterns to exclude from review coverage

4. Login and publish:

   vsce login <your-publisher-id>
   # Enter your PAT when prompted
   npm run compile
   vsce package
   vsce publish
   

5. Alternative publishing without login:

   npm run compile
   vsce package
   vsce publish -p <your-PAT>
   

6. Automated versioning and publishing:

   # To increment patch version (1.0.0 -> 1.0.1)
   npm run publish-patch
   
   # To increment minor version (1.0.0 -> 1.1.0)
   npm run publish-minor
   
   # To increment major version (1.0.0 -> 2.0.0)
   npm run publish-major
   

   These commands will automatically:

   • Increment the version number
   • Package the extension
   • Publish using the secure publishing method (PAT from .env file)

For more details, refer to the official VSCode extension publishing guide.

Performance Optimization

The extension includes several optimizations for handling large projects more efficiently:

• Lazy initialization: Directory coverage calculations are delayed by 5 seconds after activation
• Efficient pattern matching: Glob patterns are processed without excessive file system operations
• Optimized file decorations: File system access is minimized when updating decorations
• Selective processing: Only directories with reviewed files are analyzed, rather than the entire workspace

For Large Projects

If you experience slow activation or performance issues with large projects (39+ seconds activation time):

1. Disable directory coverage calculations:

   • Add "reviewLens.enableDirectoryCoverage": false to your settings
   • This disables the checkmarks on directories but maintains file decorations

2. Expand your ignore patterns to exclude large directories:

   "reviewLens.ignorePatterns": [
     "**/node_modules/**",
     "**/coverage/**",
     "**/dist/**",
     "**/build/**",
     "**/out/**",
     "**/.git/**",
     "**/.idea/**",
     "**/.next/**",
     "**/.nuxt/**",
     "**/.output/**",
     "**/.cache/**",
     "**/.parcel-cache/**",
     "**/.turbo/**",
     "**/.vercel/**",
     "**/.netlify/**",
     "**/.vite/**",
     "**/.svelte-kit/**",
     "**/public/build/**",
     "**/package-lock.json",
     "**/yarn.lock",
     "**/pnpm-lock.yaml",
     "**/*.min.js",
     "**/*.min.css",
     "**/*.map",
     "**/*.vsix",
     "**/tests/**",
     "**/vendor/**",
     "**/*.md",
     "**/.DS_Store"
   ]
   

3. Reduce refresh frequency:

   • The extension refreshes decorations on various events (file changes, editor changes)
   • If this causes performance issues, you can manually refresh when needed using:
   • Review Lens: Refresh File Decorations command

4. Structure your reviews by folders:

   • Review one folder at a time and mark completed folders as ignored
   • This reduces the number of files the extension needs to track

"reviewLens.ignorePatterns": [
  "**/node_modules/**",
  "**/coverage/**",
  "**/dist/**",
  "**/build/**",
  "**/out/**",
  "**/.git/**",
  "**/.idea/**",
  "**/.next/**",
  "**/.nuxt/**",
  "**/.output/**",
  "**/.cache/**",
  "**/.parcel-cache/**",
  "**/.turbo/**",
  "**/.vercel/**",
  "**/.netlify/**",
  "**/.vite/**",
  "**/.svelte-kit/**",
  "**/public/build/**",
  "**/package-lock.json",
  "**/yarn.lock",
  "**/pnpm-lock.yaml",
  "**/*.min.js",
  "**/*.min.css",
  "**/*.map",
  "**/*.vsix",
  "**/tests/**",
  "**/vendor/**",
  "**/*.md",
  "**/.DS_Store"
]