diff options
Diffstat (limited to 'debputy.pod')
| -rw-r--r-- | debputy.pod | 27 |
1 files changed, 24 insertions, 3 deletions
diff --git a/debputy.pod b/debputy.pod index 3ce9b90..7d08813 100644 --- a/debputy.pod +++ b/debputy.pod @@ -136,9 +136,9 @@ For packages that does not have the B<X-Style> field, B<debputy> will result to can derive a style that all parties would agree too (or the team style for packaging teams), then that style will be used. -At the time of introduction, the B<black> style is similar to that of B<wrap-and-sort -astkb>, since -that was one of the most common style according to L<https://bugs.debian.org/895570>, But the style is -expected to evolve over time and the two styles may diverge over time. +The B<black> style started as similar to that of B<wrap-and-sort -ast>, since that was one of the most +common styles according to L<https://bugs.debian.org/895570>, but the style is expected to evolve over +time and the two styles may diverge over time. The command accepts the following options: @@ -208,6 +208,12 @@ files. This command is useful for CI or for when you cannot use the language ser the same diagnostics as B<debputy lsp server> would but without requiring an LSP capable editor as intermediate. The output is only intended for human consumption. Machine readable is not a goal at this time. +The B<debputy lint> command is a form of static analysis and will not load nor execute code from the +code it is scanning. It is a security bug for B<debputy lint> to violate this principle directly +or indirectly. Therefore, B<debputy> can only provide diagnostics from libraries and tools that takes +this principle seriously. It also means that B<debputy> will likely have false-positives for self-hosting +code, since it is not allowed to load the self-hosted code. + Note that at the time of writing, the B<debputy.manifest> file is only B<partially> supported. If you have F<debian/debputy.manifest>, please also run B<debputy check-manifest> to get more thorough checks for that file for now. The B<lint> command will inform you about this issue in the output if a @@ -335,6 +341,21 @@ B<debputy lsp server> will suffice (using the stdio transport). See B<debputy ls for other integration options such as TCP (B<--tcp>) or websocket (B<--ws>) plus related supporting options. +The B<debputy lsp server> command provides several features including a form of static analysis in the +form of "as-you-type" diagnostics. For the diagnostics, is B<debputy lsp server> not allowed load nor +execute code from the code it is scanning. It is a security bug for B<debputy lsp server> to violate +this principle directly or indirectly. Therefore, B<debputy> can only provide diagnostics from libraries +and tools that takes this principle seriously. It also means that B<debputy> will likely have +false-positives for self-hosting code, since it is not allowed to load the self-hosted code. + +This security principle also applies to hover docs, completion suggestions and other trivial code editing +or viewing features. However, it is not universal, since certain LSP features are deliberately designed +to run the code you are viewing. As an example, B<debputy lsp server> can provide a "code lens" (LSP term) +for building the current package. On activation of the code lens, B<debputy> will trigger code from the +package to be run and that is expected. The critical points here are that the user most explicitly +trigger the feature and it must use terms commonly associated with running code such as B<build>, +B<run> or B<execute> (non-exhaustive list). + If you need to debug an issue with the language server, the TCP integration (B<--tcp>) can be quite helpful. In this mode, you run B<debputy lsp server --tcp> in a terminal before starting your editor. This means you have direct and unfiltered access to the B<debputy> command and its output. |