README.md

June 26, 2026 · View on GitHub

perl-lsp

perl-lsp is a native Rust language server, parser stack, and debug adapter for Perl 5.

The problem

Perl has decades of real production code, but editor tooling still struggles with the parts that matter in daily work: incomplete code while typing, cross-file navigation, package and module resolution, diagnostics, refactoring, and debugger integration.

perl-lsp is built around a native parser, semantic analysis layer, workspace index, LSP server, and DAP implementation designed for real editor use.

Status at a glance

The README is a front door, not the metric source of truth. Current release posture, corpus counts, LSP coverage, workspace receipts, and native-tooling readiness live in the status docs so the numbers can be regenerated and reviewed in one place.

Area	Source
Release posture	release status
Project status	status overview
Real Perl Editor Trust	user guide, trust dashboard
LSP and DAP coverage	LSP status, DAP status
Parser corpus and coverage	parser status
Workspace/indexing	workspace status
Native formatter and critic	native tooling status

What works

Measured editor workflows: completion, diagnostics, hover, go-to-definition, references, rename, safe-delete, semantic tokens, code actions, and workspace symbols use proof-backed paths where available and fallback or refuse unsafe cases where support is bounded.
Parser stack: native lexer, parser-core, parser facade, corpus ratchets, and tree-sitter integration.
UX testing: tracked editor UX scenarios cover first-five-minutes flows, issue-regression guards, cross-file navigation, diagnostics-after-edit, workspace churn, and rename.
Workspace intelligence: module resolution, symbol indexing, stale-index guards, multi-root workspaces, and workspace-aware rename.
Debug adapter: breakpoints, stepping, stack frames, variables, evaluate, and launch/attach flows.
Editor support: VS Code, Open VSX, Neovim, Vim, Emacs, Helix, Zed, Sublime, and any editor with LSP support.

Install

Install: docs/how-to/INSTALLATION.md
Editor setup: docs/how-to/EDITOR_SETUP.md

Current public install artifacts are public alpha. Verify the binary before wiring it into shared editor or CI configuration.

The VS Code extension downloads the matching perllsp binary automatically. Other editors use the perllsp --stdio server command after installing a release binary.

Native formatting and native critic diagnostics do not require perltidy or perlcritic. Install those tools only when a project explicitly opts into external compatibility behavior or needs legacy output comparison.

Do not install perl-lsp from crates.io; that is a different project.

Crate surface

The current architecture collapsed the old microcrate graph into a smaller published surface. Most implementation detail now lives in modules behind focused public crates.

Need	Crate
Binary language server	`perllsp`
LSP library facade	`perl-lsp-rs`
LSP implementation core	`perl-lsp-rs-core`
Parser facade	`perl-parser`
Parser engine	`perl-parser-core`
Lexer	`perl-lexer`
Semantic analysis	`perl-semantic-analyzer`
Workspace index	`perl-workspace`
Diagnostics catalog	`perl-diagnostics`
Debug adapter	`perl-dap`
Tree-sitter integration	`tree-sitter-perl-rs`, `tree-sitter-perl-c`

Documentation

Task	Link
Install	docs/how-to/INSTALLATION.md
Editor setup	docs/how-to/EDITOR_SETUP.md
Getting started	docs/tutorials/GETTING_STARTED.md
Configuration	docs/reference/CONFIG.md
Troubleshooting	docs/how-to/TROUBLESHOOTING.md
Perl setup troubleshooting	docs/how-to/PERL_SETUP_TROUBLESHOOTING.md
Editor trust and receipts	docs/how-to/EDITOR_TRUST.md
Project status and metrics	docs/project/status/index.md
Measured editor trust	docs/explanation/MEASURED_PERL_EDITOR_TRUST.md
Roadmap	docs/project/ROADMAP.md
Compiler-backed LSP roadmap	docs/project/COMPILER_BACKED_LSP_ROADMAP.md
Provider readiness contract	docs/reference/PROVIDER_READINESS_CONTRACT.md
CI gate playbook	docs/reference/CI_GATE_PLAYBOOK.md
Release history	RELEASE_HISTORY.md
Contributing	CONTRIBUTING.md
Agent workflow	AGENTS.md

How this project is built

This repository uses a documented AI-assisted development conveyor: candidate generation, ensemble curation, layered verification, CI evidence, fix-forward, and release ratchets.

Start here:

Topic	Link
Pipeline state machine	docs/articles/PIPELINE_STATE_MACHINE.md
Forensics / learning archive	docs/forensics/
Dispatch index	docs/forensics/dispatch-index.toml
Agent workflow	AGENTS.md
Contributor workflow	CONTRIBUTING.md

The short version: bad PRs should fail cheaply, duplicate PRs should close quickly, good PRs should merge safely, master should stay healthy, and every cycle should improve both the codebase and the conveyor.