Pulse Language Support for VS Code

Official Visual Studio Code extension for the Pulse programming language.

Pulse is a deterministic concurrency language that compiles to JavaScript, featuring fine-grained reactivity, CSP-style channels, and Go-inspired concurrent primitives.

Features

Core Language Support

• Syntax Highlighting: Full TextMate grammar for .pulse files with support for:

  • Keywords, control flow, declarations
  • Single-line (//) and multi-line (/* */) comments
  • String literals (double, single, template)
  • Numeric literals with underscores
  • Operators and punctuation

• Language Server Protocol (LSP): Professional-grade language server providing:

  • Auto-completion: IntelliSense for Pulse keywords and runtime functions
  • Hover Documentation: Inline documentation for keywords, functions, and symbols
  • Real-time Diagnostics: Syntax error detection using Pulse parser (debounced 150ms)
  • Semantic Tokens: Enhanced syntax highlighting based on code semantics

• Code Snippets: Quick scaffolding for common patterns:

  • Function declarations (fn, afn)
  • Reactivity (signal, computed, effect, batch)
  • Concurrency (channel, select, spawn)
  • Control flow (for, if, try)
  • Imports (impr, impc)

Advanced Features

• Dynamic Keyword Extraction: Automatically syncs with lib/lexer.js to stay current with language updates
• Command Palette: Pulse: Restart Language Server for development
• Workspace Integration: Monitors .pulse files for changes

Installation

For Local Development and Testing

1. Clone the Pulse repository (if you haven't already):

   git clone https://github.com/osvfelices/pulse.git
   cd pulse/pulse-vscode
   

2. Install dependencies:

   npm install
   

3. Build the extension:

   npm run build
   

4. Launch Extension Development Host:

   code .
   # Then press F5 in VS Code
   

5. Test the extension:

   • In the Extension Development Host window, open any .pulse file
   • Verify syntax highlighting, completions, hover, and diagnostics

From VSIX Package

1. Build the VSIX:

   npm run build
   npm run vsce:package
   

2. Install the extension:

   code --install-extension pulse-0.2.0.vsix
   

3. Reload VS Code and open a .pulse file

From VS Code Marketplace

Once published:

ext install pulselang.pulse

Usage

Syntax Highlighting

All Pulse syntax is automatically highlighted:

// Single-line comment
/* Multi-line
   comment */

import { signal, effect } from 'pulselang/runtime/reactivity'

const [count, setCount] = signal(0)

fn increment() {
  setCount(count() + 1)
}

effect(() => {
  print('Count is:', count())
})

Auto-completion

Start typing and press Ctrl+Space (or Cmd+Space on macOS):

sig[Ctrl+Space]
// Suggests: signal, with documentation

Completions include:

• Keywords: fn, let, const, select, spawn, async, await, etc.
• Runtime functions: signal, computed, effect, channel, selectCase, scheduler, print
• Documentation: Each item includes inline help

Code Snippets

Type a prefix and press Tab:

Hover Documentation

Hover over keywords and functions to see documentation:

select  // Hover shows: "CSP-style select for concurrent channel operations"

Real-time Diagnostics

Syntax errors are highlighted as you type:

fn broken( {  // Error: Syntax error
  // Missing closing parenthesis and brace

The language server uses Pulse's parser to provide accurate diagnostics with a 150ms debounce for performance.

Project Structure

pulse-vscode/
├── client/                     # VS Code extension client
│   ├── src/extension.ts       # Extension activation, LSP client
│   ├── out/                   # Compiled client code
│   └── package.json           # Client dependencies
├── server/                     # Language Server
│   ├── src/
│   │   ├── server.ts          # LSP server implementation
│   │   ├── keywords.ts        # Keyword extraction from lexer
│   │   ├── diagnostics.ts     # Syntax error detection
│   │   └── semantic-tokens.ts # Semantic highlighting
│   ├── out/                   # Compiled server code
│   └── package.json           # Server dependencies
├── test/                       # Automated tests
│   ├── suite/
│   │   ├── extension.test.ts  # Extension tests
│   │   └── fixtures/          # Test .pulse files
│   └── runTest.ts             # Test runner
├── syntaxes/
│   └── pulse.tmLanguage.json  # TextMate grammar
├── snippets/
│   └── pulse.code-snippets    # Code snippets
├── scripts/
│   └── build-and-pack.sh      # Build and package script
└── package.json                # Extension manifest

Development

Build Commands

# Install dependencies
npm install

# Build client and server
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Build tests
npm run build:test

# Run tests
npm test

# Type check all code
npm run check

# Package extension
npm run vsce:package

# All-in-one build and package
./scripts/build-and-pack.sh

Debugging

1. Open pulse-vscode/ in VS Code
2. Press F5 to launch Extension Development Host
3. Set breakpoints in client/src/extension.ts or server/src/server.ts
4. Use Debug Console to inspect values
5. Check Output panel → "Pulse Language Server" for logs

Running Tests

npm run build
npm run build:test
npm test

Tests verify:

• Extension activation
• Language detection for .pulse files
• Completions for keywords (fn, signal)
• Hover for keywords (select)
• Diagnostics for syntax errors

Modifying the Language Server

The LSP server is in server/src/:

• server.ts: Main LSP server, handles initialization, completions, hover, diagnostics
• keywords.ts: Extracts keywords from lib/lexer.js, provides hover documentation
• diagnostics.ts: Uses Pulse parser to detect syntax errors
• semantic-tokens.ts: Provides semantic highlighting (heuristic until full AST)

After changes:

npm run build
# Press F5 to test, or use "Pulse: Restart Language Server" command

Architecture

LSP Architecture

The extension uses the Language Server Protocol for better performance and separation of concerns:

┌─────────────────────────────────────┐
│   VS Code Extension Host            │
│  ┌───────────────────────────────┐  │
│  │  Client (client/src)          │  │
│  │  - Extension activation       │  │
│  │  - Language client setup      │  │
│  └───────────┬───────────────────┘  │
└──────────────┼──────────────────────┘
               │ IPC
┌──────────────┼──────────────────────┐
│  Node.js     │                      │
│  ┌───────────▼───────────────────┐  │
│  │  Server (server/src)          │  │
│  │  - Completions                │  │
│  │  - Hover                      │  │
│  │  - Diagnostics (Pulse parser) │  │
│  │  - Semantic tokens            │  │
│  │  - Keyword extraction         │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Key Design Decisions

1. Workspace Architecture: Separate client/ and server/ workspaces for clean dependency management
2. Debounced Diagnostics: 150ms debounce prevents excessive parser calls
3. Dynamic Keywords: Extracts keywords from lib/lexer.js at runtime to stay synchronized
4. Graceful Degradation: If parser fails, extension continues providing completions and hover
5. No Telemetry: Extension respects user privacy

Troubleshooting

Extension not activating

• Check Output → "Pulse Language Server" for errors
• Verify .pulse file is recognized (check status bar)
• Use command: "Pulse: Restart Language Server"

Completions not working

• Wait 2 seconds for server initialization
• Check if lib/lexer.js exists in workspace root
• Review server logs in Output panel

Diagnostics not appearing

• Ensure lib/parser.js is available in workspace
• Parser errors are logged to Output panel
• Diagnostics require valid Pulse syntax to detect errors

Build errors

# Clean and rebuild
rm -rf client/out server/out test/out node_modules
npm install
npm run build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

Reporting Issues

If you find a bug or inconsistency:

1. Check the Output panel for logs
2. Include .pulse file that reproduces the issue
3. Note VS Code version and OS
4. Open an issue at github.com/osvfelices/pulse

Roadmap

Future enhancements:

• [ ] Go to Definition
• [ ] Find All References
• [ ] Rename symbol
• [ ] Format document
• [ ] Code actions (quick fixes)
• [ ] Full AST-based semantic analysis
• [ ] Inlay hints for types
• [ ] Document symbols and outline

License

MIT License - see LICENSE file for details.

Links

• Pulse Repository
• Pulse Documentation
• Report Issues
• Changelog