work/0000775000000000000000000000000014657441233006741 5ustar work/.gitlab-ci.yml0000664000000000000000000000244614657441233011403 0ustar # TODO: Figure out if we can reuse these jobs but run them after our own checks without having # to manually merge `stages`. include: - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/salsa-ci.yml - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/pipeline-jobs.yml stages: - ci-test - provisioning - build - publish - test variables: SALSA_CI_DISABLE_WRAP_AND_SORT: 1 SALSA_CI_DISABLE_APTLY: 0 debputy-reformat: stage: ci-test image: debian:unstable-slim script: - apt-get update -qq && apt-get -qq install --yes debputy python3-lsprotocol - debputy reformat --linter-exit-code --no-auto-fix except: variables: - $CI_COMMIT_TAG != null && $SALSA_CI_ENABLE_PIPELINE_ON_TAGS !~ /^(1|yes|true)$/ debputy-lint: stage: ci-test image: debian:sid-slim script: - apt-get update -qq && apt-get -qq install --yes debputy python3-lsprotocol python3-levenshtein python3-junit.xml - debputy lint --lint-report-format=junit4-xml --report-output debputy-lint-report.xml # Mostly just for the validation that --spellcheck does not crash - debputy lint --spellcheck except: variables: - $CI_COMMIT_TAG != null && $SALSA_CI_ENABLE_PIPELINE_ON_TAGS !~ /^(1|yes|true)$/ artifacts: reports: junit: debputy-lint-report.xml work/CONTRIBUTING.md0000664000000000000000000000361414657441233011176 0ustar # Contributing to the debputy-lsp project The [debputy][debputy-repo] and `debputy-lsp` project welcome contributing. Generally, you can help by: 1. Providing editor configuration 2. Provide patches, new features or bug fixes [debputy-repo]: https://salsa.debian.org/debian/debputy/ ## Provide editor configuration Ideally, the editor should bring its own editor configuration for language servers. This project will host editor configuration where this currenlty not the case or where upstreaming is non-trivial. However, please only provide copyrightable editor glue configuration where: 1. You provide it the `EXPAT` or `MIT` license terms. As stated, `debputy-lsp` is ideally a temporary host and not a permanent host for such files and a very permissive license enables us to outsource editor configuration. 2. It is generally applicable and can reasonable be upstremable. That is usually the minimal LSP glue needed with some comments or suggestions. Providing non-controversial defaults for certain features is acceptable. If the editor already has glue out of the box, you are welcome to submit a link / reference to their documentation, such that the `debputy lsp editor-config` command can provide the details. Note: Changes to `debputy lsp editor-config` should generally be done against [debputy][debputy-repo] project. ## Provide patches, new features or bug fixes These are generally welcome as well. At the time of writing, those should be done via the [debputy][debputy-repo] project. Note that the `debputy` repo uses a different license than the ones used for the editor glue provided by `debputy-lsp`. For new features, it might be a good idea to check whether it is in scope for `debputy lsp` before doing it. The `debputy lsp` part has a narrower scope than `lintian` and some other QA tools. That implies that many `lintian` checks will never be provided by `debputy`. work/README.md0000664000000000000000000001273714657441233010232 0ustar # debputy-lsp - Editor support for Debian packaging files This project provides editor support for Debian packaging files via the `debputy` language server (`debputy lsp server`). Any editor that has [LSP] support (sometimes via plugin) from a compatible version of the specification can use `debputy`'s language server to provide extra features when working on Debian packaging files. At the time of writing, the actual language server code is provided by [`debputy`](https://salsa.debian.org/debian/debputy) itself. This repo instead focuses on simplifying the installation, documentation and providing editor configuration that be trivially moved out of the `debputy` source. The `debputy-lsp` and `debputy` repos are split on a technicality, since `debputy` is also a packaging helper and therefore has to be very conservative with both runtime and build-time dependencies from the source package. The `debputy` source package is also a key package (by virtue key packages using it as a build-dependency). Therefore, adding an new binary package with extra depenencies would immediately make all of them key packages. Splitting out `debputy-lsp` into a separate repo grants it a lot more freedom in that regard, which in turn enables it to be a lot more user friendly in its promises and features without bloating the set of Debian key packages. This matches prior art on this area with `cmake`, which had its emacs support split into a separate `emacs-cmake-mode` source package to avoid making parts of the emacs stack key packages. [LSP]: https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/ ## What kind of editor features can I expect? The LSP involves feature negotiation, so the concrete feature set depends on the editor. Additionally, `debputy` also have some feature limitations for certain files. Some common features are: * As-you-type diagnostics with quick-fixes (Use `debputy lint` for a batch version) * Context aware completion suggestions * In-editor access to documentation (often called "hover docs") Other features include: * Reformat on save provided there is a known formatting (Check with `debputy reformat --no-auto-fix`) ## What kind of files are supported? Source packaging files such as: * `debian/control` * `debian/copyright` (DEP-5 format only) * `debian/tests/control` * `debian/debputy.manifest` Known omissions to support include any produced artifact or "read-only" file from the build process such as: * `DEBIAN/control` (the .deb counter part of `debian/source`) * Any `*.dsc` or `*.changes` file # Known issues ## Editor configuration - file type required Editors need to know which language server to apply to which file type and the language server specification deliberately does not cover "how" this is done (only how the editor and the server will communicate and how features work). Most editors seem to prefer the approach of associating a file with a type (usually relying on file patterns) and then the file type can be associated with a language server. This mechanism implies that has the weakness that to activate a language server, the editor must have a basic file type declared first. Since the Debian file types are very niche features, few editors support these files types (or support them out of the box). The simple solution is to ensure you install the optional file types required as needed (like `elpa-dpkg-dev-el` for `emacs`) and then associate the files with the most specific type you can. However, you may find that some files cannot easily be linked to the `debputy` language server because of this. Notably, support for `debian/tests/control` is lot rarer than `debian/control` support, which in turn reflects in `debputy`'s own suggestions for editor configuration. ## Editor configuration - language IDs By virtue of how the specification works, the editor is expected to provide `debputy` with a language ID for the files being worked on. The specification has a list of known language IDs for common programming languages. The Debian packaging files are *not* on this list, so there are no known reference point for these language IDs. Instead, `debputy` has a list of "acceptable" language IDs associated with the file names it knows how to handle. As an example, when working on a `debian/control` file, `debputy` will accept `debian/control`, `debian-control` and `debcontrol` as "language ID" for that file. Additionally, if empty language ID is provided, `debputy` uses filename based detection (is the file named `.../debian/control`?) . If you can control the language ID, please use the same name as the file for maximum compatibility. Alternatively, if you have it use an empty language ID that usually also works. However, if neither of those are an option and the language ID used by the editor is not supported by `debputy`, you can add the `--ignore-language-ids` argument `debputy lsp server` command line and `debputy` will ignore language IDs in favor of filename based detection. This has its limitations in some corner cases. However, the common case should work. Note: For some case, `debputy` also does a filename based check. As an example, if `debputy` receives request with a language ID of `yaml` (that ID is defined by the specification), then `debputy` only reacts to it if the file is a known YAML-based file (at the time of writing `debian/debputy.manifest` is the only supported case). This is to enable using a standard language where necessary available (in case the editor insists on sticking to only known language IDs). work/debian/0000775000000000000000000000000014657441233010163 5ustar work/debian/changelog0000664000000000000000000000102514657441233012033 0ustar debputy-lsp (0.2.1) unstable; urgency=medium * d/tests/control: Add missing `allow-stderr` -- Niels Thykier Thu, 15 Aug 2024 18:02:03 +0000 debputy-lsp (0.2) unstable; urgency=medium * Source upload now that the package has cleared NEW. * autopkgtests: Add basic test that the LSP can start -- Niels Thykier Thu, 15 Aug 2024 17:22:06 +0000 debputy-lsp (0.1) unstable; urgency=medium * Initial release. -- Niels Thykier Sun, 11 Aug 2024 19:26:49 +0000 work/debian/control0000664000000000000000000000462014657441233011570 0ustar Source: debputy-lsp Section: devel Priority: optional Standards-Version: 4.7.0 Maintainer: Debputy Maintainers Uploaders: Niels Thykier , Build-Depends: debputy (>= 0.1.45~), dpkg-dev (>= 1.22.7~), # Dear FTP-masters, if you are looking for `debian/rules`, # then it got replaced by the Build-Driver here! # # If you are wondering why it is not in the `debputy` source, # then please the upstream README.md Build-Driver: debputy X-Style: black Homepage: https://salsa.debian.org/debian/debputy/ Vcs-Git: https://salsa.debian.org/debian/debputy-lsp.git Vcs-Browser: https://salsa.debian.org/debian/debputy-lsp Package: debputy-lsp Architecture: all Multi-Arch: foreign Depends: debputy (>= 0.1.46~), python3-lsprotocol, python3-pygls, Recommends: hunspell-en-us, python3-hunspell, python3-levenshtein, Suggests: python3-junit-xml, Description: Editor support for Debian packaging files via LSP specification Dependency package that installs the minimal dependencies required for for the debputy language server, which can provide editor support via the Language Server Protocol (LSP). This package will also provide relevant dependencies for many of debputy assistance commands such as "debputy lint" and "debputy reformat". . Any editor with LSP support built with a compatible version of the LSP specification can interface with the debputy language server and use it to extend its feature set for Debian packaging files (debian/). . Concrete features depends on the editor in question, but common supported editor features include: . * As-you-type diagnostics with quick-fixes * Context aware completion suggestions * In-editor access to documentation (often called "hover docs") . The "Suggests" field may have a package dedicated to your favorite editor. If so, consider installing that instead as it will then also provide most of the relevant editor glue to enable debputy automatically. Otherwise, you still have to provide your own editor-side of the configuration to have it start debputy when you start editing debian packaging files. . For more information about the LSP specification, please see: https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/ . For a list of tools / editors that supports some version of the LSP specification, please see: https://microsoft.github.io/language-server-protocol/implementors/tools/ work/debian/copyright0000664000000000000000000000224714657441233012123 0ustar Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Files: * Copyright: 2024 Niels Thykier License: MIT Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: . The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. . THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. work/debian/gbp.conf0000664000000000000000000000020414657441233011576 0ustar [DEFAULT] debian-branch = main [dch] multimaint-merge = true ignore-regex = (Signed-off|Acked|Tested|Reviewed)-by:|Fix-For:|Fixes: work/debian/tests/0000775000000000000000000000000014657441233011325 5ustar work/debian/tests/control0000664000000000000000000000014014657441233012723 0ustar Tests: debputy-cli-lsp, Depends: @, @recommends@, Restrictions: allow-stderr, superficial, work/debian/tests/debputy-cli-lsp0000775000000000000000000000011314657441233014263 0ustar #!/bin/sh set -e -u -x debputy lsp features debputy lsp server