Development¶
The single entry point for working on pain001-lsp: toolchain, how to
reproduce every CI gate locally, where tests live, and how a release
happens. CONTRIBUTING.md
covers the etiquette (DCO, commit format, review); this file covers the
mechanics.
Toolchain¶
Tool |
Version |
Where it is pinned |
|---|---|---|
Python |
3.11 is the floor; CI runs 3.11 to 3.14 |
|
Poetry |
2.x |
|
Node.js |
22 |
only for the VS Code extension ( |
Docker |
any |
only for the container image ( |
git clone https://github.com/sebastienrousseau/pain001-lsp
cd pain001-lsp
poetry install --all-extras
make check
pre-commit install (with pre-commit on your
PATH) runs the hygiene hooks, ruff, black, codespell and mypy on each
commit; .pre-commit-config.yaml pins every hook by exact release.
The devcontainer
does the same in a Codespace or VS Code container: it installs Poetry
and pre-commit, installs the project and finishes by running
make check.
Reproducing every CI gate¶
Each CI job maps onto a local command, so a red job can be reproduced
without reading YAML. make check runs every gate in the first block.
Gate |
Local command |
CI workflow |
|---|---|---|
Lint (ruff, black) |
|
|
Types (mypy |
|
|
Security lint (bandit) |
|
|
Complexity ceilings (cyclomatic 10, cognitive 15, Halstead difficulty 30, 60 lines per function, 500 per file) against |
|
|
Version sources agree |
|
|
Tests with the 100 % line and branch coverage floor |
|
|
Docstring coverage (interrogate, 100 %) |
|
|
Examples run |
|
|
Spelling (codespell) |
|
|
Markdown style |
|
|
Locked dependency set |
|
|
Lockfile matches |
|
|
Benchmarks (kept running, not asserted) |
|
|
Dependency advisories |
|
|
Fuzzing (Atheris) |
|
|
Mutation testing (85 % floor) |
|
|
Manual build, Sphinx warnings as errors |
|
|
Link check of the manual |
|
|
VS Code extension |
|
|
Container image |
|
|
Sign-off on every commit |
|
|
make docs and make linkcheck need the Sphinx toolchain, which is
not in the Poetry environment: in a separate virtual environment, run
pip install --require-hashes -r requirements/docs.txt and
pip install --no-deps -e ., then pass its interpreter as
make docs PYTHON=<venv>/bin/python.
The coverage floor is 100 % line and branch, set once in
[tool.coverage.report] in pyproject.toml, so a plain pytest
enforces it too. # pragma: no cover is kept for the defensive guards
that no valid message type can reach (see
ARCHITECTURE.md).
Test layout¶
tests/
test_lsp_server.py the pure helpers and the in-process handlers
test_stdio_e2e.py the server as a subprocess over stdio
test_diagnostic_shapes.py positions and shapes of the diagnostics
test_corpus_commands.py the example-corpus workspace commands
test_faces_commands.py the faces workspace commands
test_benchmarks.py the linear-scaling guard
test_fuzz_harness.py the Atheris harness runs on fixed inputs
test_vscode_extension.py the extension offers what the server accepts
test_readme.py README shape, links and Python snippets
test_check_*.py, test_verify_versions.py, test_release_notes.py
the release and CI helpers under scripts/
test_workflow_pinning.py every CI install is hash-pinned
test_headers.py SPDX headers
test_suite_conformance.py the family-wide rules; vendored, do not edit here
examples/ numbered scripts; every one runs in CI
benches/ the diagnostics benchmark
fuzz/ Atheris harness for the document handlers
Documentation¶
Sphinx with MyST under docs/ is the only documentation root. Root
Markdown files (README.md, ARCHITECTURE.md, this file,
CHANGELOG.md, ROADMAP.md) are included into the manual by thin
chapter files under docs/, so each is edited in one place. Write a
file name in backticks or as a link: MyST’s linkify turns a bare
NAME.md into a link to a host under the .md domain, which the link
check then reports as broken. Decisions that will be
questioned later get an ADR in docs/adr/. docs.yml deploys the
manual to GitHub Pages from main.
Versioning and release¶
One version number, restated in
pyproject.toml,pain001_lsp/__init__.py,CITATION.cff, the README’s latest-release line and the VS Code extension;scripts/verify_versions.pyfails when they disagree.The line is
0.0.x, every release is one step up, and the package ships the same number as the corepain001library, which releases first.Releases are cut by a signed tag on
main;release.ymlbuilds, publishes to PyPI with trusted publishing and writes the release page. RELEASING.md is the checklist.