MooseStack

moosestack-lsp

Language Server for Moose projects. Provides real-time SQL syntax validation for SQL strings embedded in TypeScript sql tagged templates and Python sql() function calls.

Editor Features

These features appear directly in your IDE when editing sql tagged template literals (TypeScript) or sql() function calls (Python):

Feature	What You See in Your Editor
Error Diagnostics	Red squiggly underlines on SQL syntax errors with error messages
Auto-Complete	Popup suggestions for ClickHouse functions, keywords, data types, table engines, formats, and settings
Context-Aware Completions	Only relevant completions based on cursor position (e.g., only table engines after ENGINE =, only formats after FORMAT)
Hover Documentation	Tooltip with syntax, description, and examples when you hover over any ClickHouse function, keyword, or type
Code Actions	"Format SQL" action available in your editor's quick-fix menu to auto-format SQL strings (TypeScript only)
Snippet Support	Function completions insert with tab stops for parameters (e.g., toHour($1))

Additional Features

• ClickHouse dialect - Uses the same SQL parser as the Moose CLI
• ClickHouse version awareness - Detects your ClickHouse version from docker-compose.yml and provides version-appropriate completions
• Editor agnostic - Works with any LSP-compatible editor
• Monorepo support - Automatically detects Moose projects in subdirectories
• Zero configuration - Just install and it works

Prerequisites

• Node.js 18+ (for running the LSP server)
• A Moose project with:
  • TypeScript: @514labs/moose-lib in package.json
  • Python: moose-lib in pyproject.toml, requirements.txt, or setup.py
• An LSP-compatible editor

Installation

From npm

npm install -g @514labs/moose-lsp

Verify installation:

which moosestack-lsp

From Source

See Development for build prerequisites and instructions. After building, link the package globally:

cd packages/lsp-server
pnpm link --global

Verify installation:

which moosestack-lsp

Editor Setup

Neovim (with LazyVim)

Add to ~/.config/nvim/lua/plugins/moosestack-lsp.lua:

-- Setup moosestack LSP after plugins load
vim.api.nvim_create_autocmd("User", {
  pattern = "LazyDone",
  callback = function()
    local lspconfig = require("lspconfig")
    local configs = require("lspconfig.configs")

    if not configs.moosestack then
      configs.moosestack = {
        default_config = {
          cmd = { "moosestack-lsp", "--stdio" },
          filetypes = { "typescript", "python" },
          root_dir = lspconfig.util.root_pattern("moose.config.toml", "package.json", "pyproject.toml"),
        },
      }
    end

    lspconfig.moosestack.setup({})
  end,
})

return {}

VS Code / Cursor

The extension is published to both the VS Code Marketplace and Open VSX Registry (used by Cursor). To install:

1. Open VS Code or Cursor
2. Press Cmd+Shift+X (Mac) or Ctrl+Shift+X (Windows/Linux) to open Extensions
3. Search for "MooseStack LSP" or "moosestack-lsp"
4. Click Install

That's it! The extension will automatically start when you open TypeScript or Python files in a Moose project.

Verify It's Working

For TypeScript:

1. Open a TypeScript file in a Moose project (must have @514labs/moose-lib in package.json)
2. Type some SQL in a sql tagged template literal
3. You should see:
   • Error diagnostics (red squiggles) for invalid SQL
   • Completions when typing in SQL strings (press Ctrl+Space or Cmd+Space)
   • Hover documentation when hovering over ClickHouse functions

For Python:

1. Open a Python file in a Moose project (must have moose-lib in pyproject.toml or requirements.txt)
2. Type some SQL in a sql() function call or f-string with :col format
3. You should see the same diagnostics, completions, and hover documentation

How It Works

1. Project Detection - The LSP searches for:
   • package.json files containing @514labs/moose-lib (TypeScript)
   • pyproject.toml, requirements.txt, or setup.py containing moose-lib (Python)
2. Source Analysis:
   • TypeScript: Uses the TypeScript compiler API to parse source files and find sql tagged template literals
   • Python: Uses tree-sitter to parse Python files and find sql() function calls and f-strings with :col format
3. Validation - Each SQL string is validated using a WASM-compiled Rust SQL parser with ClickHouse dialect
4. Diagnostics - Validation errors are published as LSP diagnostics, appearing as error squiggles in your editor

Development

Building from Source

Prerequisites: Rust, wasm-pack, pnpm

# Clone the repository
git clone https://github.com/514-labs/moosestack-lsp.git
cd moosestack-lsp

# Install dependencies
pnpm install

# Build all packages (includes WASM compilation)
pnpm build

# Run tests
pnpm test

# Lint (Biome + Clippy)
pnpm lint

Project Structure

moosestack-lsp/
├── packages/
│   ├── sql-validator/         # Rust SQL validator (compiles to WASM)
│   ├── sql-validator-wasm/    # WASM wrapper + TypeScript bindings
│   ├── lsp-server/            # LSP server implementation
│   └── vscode-extension/      # VS Code/Cursor extension
├── scripts/
│   └── release.sh             # Release automation script
└── .github/workflows/         # CI/CD pipelines

Troubleshooting

No diagnostics appearing

1. Check your editor's LSP logs to ensure the server is starting
2. Verify your project has:
   • TypeScript: @514labs/moose-lib in package.json dependencies
   • Python: moose-lib in pyproject.toml, requirements.txt, or setup.py
3. Ensure you're editing .ts or .py files
4. For TypeScript: Check that tsconfig.json exists in your project root

Roadmap

• As-you-type validation
• SQL completions with intelligent sorting (functions, keywords, types, engines, formats)
• Hover documentation for ClickHouse functions and types
• ClickHouse version detection
• Context-aware completions (show only relevant items based on SQL context)
• VS Code extension
• Python support

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

License

MIT

Made by

The team at Fiveonefour labs, the maintainers of MooseStack.