Adding upstream version 0.1.48.upstream/0.1.48upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.