perl-lsp is a native Rust language server, parser stack, and debug adapter for Perl 5.
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.
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 |
- 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: 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.
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 |
| 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 |
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.
See CONTRIBUTING.md. AI implementation agents should read AGENTS.md first.
Release artifacts include SBOM generation and provenance attestations. See Supply Chain Security.
Dual licensed under MIT or Apache-2.0: LICENSE-MIT / LICENSE-APACHE.