VSCode Projectionist

A VSCode extension that provides project-aware file navigation and creation, inspired by vim-projectionist by Tim Pope.

Attribution

This extension is inspired by and based on concepts from Tim Pope's excellent vim-projectionist plugin. We're grateful for his innovative work in creating the original projectionist system that enables efficient project navigation.

Features

• Alternate File Navigation: Quickly switch between related files (e.g., source ↔ test)
• Related File Discovery: Find all files related to the current file
• Auto-scroll to Definitions: Automatically scroll to relevant sections in related files (new!)
• Template-based File Creation: Create new files with predefined templates
• Project Configuration: Configure file relationships via .projections.json

Commands

• Switch to Alternate File (Ctrl+A): Navigate to the alternate file
• Switch to Related File: Show quick pick of all related files
• Create File from Template: Create a new file with template content
• Reload Projections: Reload the .projections.json configuration

Configuration

Create a .projections.json file in your project root to define file relationships:

{
  "src/*.ts": {
    "alternate": "test/{}.test.ts",
    "type": "source",
    "template": [
      "export class {} {",
      "    // Implementation here",
      "}"
    ]
  },
  "test/*.test.ts": {
    "alternate": "src/{}.ts",
    "type": "test"
  }
}

Configuration Options

• alternate: Primary alternate file pattern
• related: Array of related file patterns
• type: File type identifier
• template: Array of template lines for new files
• define: Search pattern to find and scroll to in related files (new!)

Development

Testing

This project includes comprehensive tests covering all core functionality:

npm install          # Install dependencies
npm run compile      # Compile TypeScript
npm run lint         # Run ESLint
npm test             # Run all tests

Test Structure

• test/suite/transformations.test.ts - Tests for placeholder transformations
• test/suite/projections.test.ts - Tests for projection management and file matching
• test/suite/extension.test.ts - Integration tests for VSCode extension

Running Individual Tests

Use VSCode's built-in test runner or:

npm run compile && npm test

Placeholders and Transformations

Use {} as a placeholder for the matched portion of the file path. You can apply transformations:

• {|dot}: Replace / with .
• {|underscore}: Replace / with _
• {|camelcase}: Convert to camelCase
• {|snakecase}: Convert to snake_case
• {|uppercase}: Convert to UPPERCASE
• {|lowercase}: Convert to lowercase
• {|dirname}: Get directory name
• {|basename}: Get file name
• {|file}: Get file name without extension
• {|ext}: Get file extension
• {|plural}: Pluralize the word (user → users, category → categories)
• {|singular}: Singularize the word (users → user, categories → category)

Example Configurations

React Project

{
  "src/components/*.tsx": {
    "alternate": "src/components/{}.test.tsx",
    "related": ["src/components/{}.module.css", "src/components/{}.stories.tsx"],
    "template": [
      "import React from 'react';",
      "",
      "export const {}: React.FC = () => {",
      "    return <div>{}</div>;",
      "};"
    ]
  }
}

Java Project

{
  "src/main/java/**/*.java": {
    "alternate": "src/test/java/{}.java",
    "template": [
      "package {|dirname|dot};",
      "",
      "public class {} {",
      "",
      "}"
    ]
  }
}

Rails Project (with auto-scroll to table definition)

{
  "app/models/*.rb": {
    "related": ["db/schema.rb", "db/structure.sql"],
    "define": "create_table \"{|plural}\"",
    "type": "model"
  }
}

When you open a related file from app/models/user.rb, the extension will:

1. Expand {|plural} to transform user → users
2. Search for the pattern create_table "users" in the related file
3. Automatically scroll to that line

See examples/rails-app/ for a working example!

Auto-scroll with Define Patterns

The define configuration option allows you to automatically scroll to specific patterns when opening related files. This is especially useful for navigating to relevant definitions in large files.

How It Works

1. Pattern Matching: When you open a related file, the extension searches for the pattern
2. Placeholder Expansion: The pattern supports all transformations (plural, snakecase, etc.)
3. Smart Search: Tries literal string match first, then falls back to regex if needed
4. Auto-scroll: Scrolls to the found line and centers it in the editor

Pattern Types

The define pattern can be:

• Literal text: "create_table \"users\""
• With placeholders: "create_table \"{|plural}\""
• Regex pattern: "create_table.*{|plural}"
• With multiple transformations: "CREATE TABLE {|snakecase|plural}"

Use Cases

• Rails: Navigate from models to schema table definitions
• Documentation: Jump to specific sections in docs
• Configuration: Find settings by key name
• API: Locate endpoint definitions in route files

Installation

1. Package the extension: vsce package
2. Install the .vsix file in VSCode

Development

1. Clone this repository
2. Run npm install
3. Run npm run compile
4. Press F5 to launch a new Extension Development Host

Differences from vim-projectionist

While this extension is inspired by vim-projectionist, there are some differences due to the VSCode environment:

• UI Integration: Uses VSCode's quick pick interface instead of Vim's command line
• File System: Uses VSCode's file system APIs for better integration
• Configuration: Same .projections.json format for compatibility
• Commands: Adapted to VSCode's command palette system

Contributing Back

If you find this extension useful, please consider:

• ⭐ Starring Tim Pope's original vim-projectionist
• 💝 Supporting Tim Pope's work through GitHub Sponsors
• 🐛 Reporting issues or contributing to vim-projectionist if you use Vim

License

MIT - See LICENSE file for details.

This project includes attribution to Tim Pope's original vim-projectionist work.