Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (43 loc) · 2.9 KB

AGENTS.md

File metadata and controls

58 lines (43 loc) · 2.9 KB

VSCodeVim — Agent Instructions

VSCodeVim is a VS Code extension (TypeScript) that emulates Vim modal editing. It targets both desktop and web VS Code environments.

Build & Test

yarn build-dev       # Fast dev build
yarn build           # Production build
yarn watch           # Rebuild on file changes

yarn build-test && yarn test   # Run tests locally (close all VS Code instances first)
npx gulp test                  # Run tests in Docker (preferred)
npx gulp test --grep <REGEX>   # Run filtered tests in Docker

yarn lint            # Check code style
yarn lint:fix        # Auto-fix linting issues
yarn prettier        # Format code

Architecture

Event flow: Key press → extension.ts → ModeHandler.handleKeyEvent() → action matching → runAction() → updateView()

Key directories:

  • src/actions/ — All command/motion/operator implementations; large consolidated files (e.g. insert.ts, search.ts) are intentional
  • src/actions/plugins/ — Emulated Vim plugins (easymotion, surround, sneak, commentary, etc.)
  • src/mode/modeHandler.ts — Central state machine; one instance per open editor
  • src/state/vimState.ts — Per-editor state (cursor, registers, mode, history)
  • src/state/recordedState.ts — Transient state for the current operation; resets after each action
  • src/cmd_line/ — Ex command (:) parsing and execution
  • src/configuration/ — Settings loading and validation
  • src/neovim/ — Optional Neovim process integration for Ex commands
  • src/platform/node/ and src/platform/browser/ — Platform-specific abstractions
  • test/ — Mirrors src/ structure; uses Mocha + Sinon + @vscode/test-electron

Three action base classes:

  • BaseMovement — Updates cursor only; returns Position or IMovement (start+end for text objects)
  • BaseCommand — Modifies VimState beyond cursor movement
  • BaseOperator — Combines with a movement (e.g. d{motion}, c{motion})

Conventions

  • TypeScript strict: true + noImplicitOverride: true — always use the override keyword when overriding parent methods
  • IMovement interface (not just Position) is required when a motion needs to return a range (e.g. text objects like aw, i{)
  • Platform abstraction via /src/platform/ — never call Node.js APIs directly; use the abstraction layer so web VS Code works
  • Settings precedence: Ex-commands → user/workspace VS Code settings → defaults
  • .vimrc support is remaps-only — no full Vimscript execution
  • Actions are registered by decorating classes; see existing action files for the pattern

References

  • CONTRIBUTING.md — Setup, architecture deep-dive, release process
  • README.md — All supported settings, emulated plugins, keybindings
  • gulpfile.js — Build/test/release automation tasks
  • package.json — Extension manifest, all configuration schema definitions (40+ settings)