Merge pull request #30 from docker/configure-overlapping-dockerfile-diagnostics

Add initialization option to suppress some Dockerfile diagnostics

Author: rcjsuen

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the Docker Language Server will be documented in this file.
 
+## Unreleased
+
+### Added
+
+- Dockerfile
+  - textDocument/publishDiagnostics
+    - introduce a setting to ignore certain diagnostics to not duplicate the ones from the Dockerfile Language Server
+
 ## 0.1.0 - 2025-03-31
 
 ### Added

README.md

@@ -69,6 +69,20 @@ Use "docker-language-server [command] --help" for more information about a comma
 
 ## Language Server Configuration
 
+### Initialization Options
+
+On startup, the client can include initizliation options on the initial `initialize` request. If the client is also using [rcjsuen/dockerfile-language-server](https://github.com/rcjsuen/dockerfile-language-server), then some results in `textDocument/publishDiagnostics` will be duplicated across the two language servers. By setting the _experimental_ `dockerfileExperimental.removeOverlappingIssues` to `true`, the Docker Language Server will suppress the duplicated results. Note that this setting may be renamed or removed at any time.
+
+```JSONC
+{
+  "initializationOptions": {
+    "dockerfileExperimental": {
+      "removeOverlappingIssues:": true | false
+    }
+  }
+}
+```
+
 ### Experimental Capabilities
 
 To support `textDocument/codeLens`, the client must provide a command with the id `dockerLspClient.bake.build` for executing the build. If this is supported, the client can define its experimental capabilities as follows. The server will then respond that it supports code lens requests and return results for `textDocument/codeLens` requests for Bake HCL files.

e2e-tests/publishDiagnostics_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 
 	"github.com/docker/docker-language-server/internal/bake/hcl"
+	"github.com/docker/docker-language-server/internal/pkg/buildkit"
 	"github.com/docker/docker-language-server/internal/pkg/cli/metadata"
 	"github.com/docker/docker-language-server/internal/tliron/glsp/protocol"
 	"github.com/docker/docker-language-server/internal/types"
@@ -26,6 +27,8 @@ func (h *PublishDiagnosticsHandler) Handle(_ context.Context, conn *jsonrpc2.Con
 	switch request.Method {
 	case protocol.ServerTextDocumentPublishDiagnostics:
 		if request.Notif && request.Params != nil {
+			// always deserialize to a completely new struct
+			h.diagnostics = protocol.PublishDiagnosticsParams{}
 			require.NoError(h.t, json.Unmarshal(*request.Params, &h.diagnostics))
 			h.responseChannel <- nil
 		}
@@ -40,6 +43,13 @@ func TestPublishDiagnostics(t *testing.T) {
 	// ensure the language server works without any workspace folders
 	testPublishDiagnostics(t, protocol.InitializeParams{})
 
+	// ensure the language server works without any workspace folders
+	testPublishDiagnostics(t, protocol.InitializeParams{
+		InitializationOptions: map[string]any{
+			"dockerfileExperimental": map[string]bool{"removeOverlappingIssues": true},
+		},
+	})
+
 	homedir, err := os.UserHomeDir()
 	require.NoError(t, err)
 
@@ -106,27 +116,33 @@ func testPublishDiagnostics(t *testing.T, initializeParams protocol.InitializePa
 		clientStream,
 		handler,
 	)
+	defer func() {
+		buildkit.RemoveOverlappingIssues = false
+	}()
 	initialize(t, conn, initializeParams)
 
 	homedir, err := os.UserHomeDir()
 	require.NoError(t, err)
 
 	testCases := []struct {
-		name        string
-		content     string
-		included    []bool
-		diagnostics []protocol.Diagnostic
+		name             string
+		content          string
+		included         []bool
+		overlappingIssue bool
+		diagnostics      []protocol.Diagnostic
 	}{
 		{
-			name:        "no diagnostics",
-			content:     "FROM scratch",
-			included:    []bool{},
-			diagnostics: []protocol.Diagnostic{},
+			name:             "no diagnostics",
+			content:          "FROM scratch",
+			included:         []bool{},
+			overlappingIssue: false,
+			diagnostics:      []protocol.Diagnostic{},
 		},
 		{
-			name:     "MAINTAINER is deprecated",
-			content:  "FROM alpine:3.16.1\nMAINTAINER x",
-			included: []bool{true, false, false, false},
+			name:             "MAINTAINER is deprecated",
+			content:          "FROM scratch\nMAINTAINER x",
+			included:         []bool{true},
+			overlappingIssue: true,
 			diagnostics: []protocol.Diagnostic{
 				{
 					Message:  "The MAINTAINER instruction is deprecated, use a label instead to define an image author (Maintainer instruction is deprecated in favor of using label)",
@@ -148,6 +164,27 @@ func testPublishDiagnostics(t *testing.T, initializeParams protocol.InitializePa
 						},
 					},
 				},
+			},
+		},
+		{
+			name:             "JSON args",
+			content:          "FROM alpine:3.16.1\nCMD ls",
+			included:         []bool{true, false, false, false},
+			overlappingIssue: false,
+			diagnostics: []protocol.Diagnostic{
+				{
+					Message:  "JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals (JSON arguments recommended for CMD to prevent unintended behavior related to OS signals)",
+					Source:   types.CreateStringPointer("docker-language-server"),
+					Severity: types.CreateDiagnosticSeverityPointer(protocol.DiagnosticSeverityWarning),
+					Code:     &protocol.IntegerOrString{Value: "JSONArgsRecommended"},
+					CodeDescription: &protocol.CodeDescription{
+						HRef: "https://docs.docker.com/go/dockerfile/rule/json-args-recommended/",
+					},
+					Range: protocol.Range{
+						Start: protocol.Position{Line: 1, Character: 0},
+						End:   protocol.Position{Line: 1, Character: 6},
+					},
+				},
 				{
 					Message:  "The image can be pinned to a digest",
 					Source:   types.CreateStringPointer("docker-language-server"),
@@ -205,8 +242,17 @@ func testPublishDiagnostics(t *testing.T, initializeParams protocol.InitializePa
 		},
 	}
 
+	removeOverlappingIssues := false
+	if options, ok := initializeParams.InitializationOptions.(map[string]any); ok {
+		if settings, ok := options["dockerfileExperimental"].(map[string]bool); ok {
+			if value, ok := settings["removeOverlappingIssues"]; ok {
+				removeOverlappingIssues = value
+			}
+		}
+	}
+
 	for _, tc := range testCases {
-		t.Run(fmt.Sprintf("%v (len(workspaceFolders) == %v)", tc.name, len(initializeParams.WorkspaceFolders)), func(t *testing.T) {
+		t.Run(fmt.Sprintf("%v (len(workspaceFolders) == %v, removeOverlappingIssues=%v)", tc.name, len(initializeParams.WorkspaceFolders), removeOverlappingIssues), func(t *testing.T) {
 			didOpen := createDidOpenTextDocumentParams(homedir, t.Name(), tc.content, "dockerfile")
 			err := conn.Notify(context.Background(), protocol.MethodTextDocumentDidOpen, didOpen)
 			require.NoError(t, err)
@@ -224,6 +270,12 @@ func testPublishDiagnostics(t *testing.T, initializeParams protocol.InitializePa
 			} else {
 				filteredDiagnostics = tc.diagnostics
 			}
+
+			if removeOverlappingIssues && tc.overlappingIssue {
+				filteredDiagnostics = []protocol.Diagnostic{}
+			}
+
+			require.Equal(t, didOpen.TextDocument.URI, params.URI)
 			require.Equal(t, filteredDiagnostics, params.Diagnostics)
 			require.Equal(t, int32(1), *params.Version)
 		})

internal/pkg/buildkit/service.go

@@ -28,6 +28,11 @@ type BuildOutput struct {
 type BuildKitDiagnosticsCollector struct {
 }
 
+// RemoveOverlappingIssues can be used to decide if diagnostics that
+// overlap with what dockerfile-utils generates should be removed or
+// not.
+var RemoveOverlappingIssues = false
+
 var unknownFlagRegexp *regexp.Regexp
 var commandMajorityFlagRegexp *regexp.Regexp
 
@@ -256,8 +261,42 @@ func parse(contextPath, source string, doc document.DockerfileDocument, content
 	return lintWithBuildKitBinary(escapedPath, source, doc, content)
 }
 
+func shouldIgnore(diagnostic protocol.Diagnostic) bool {
+	if *diagnostic.Severity == protocol.DiagnosticSeverityError {
+		return true
+	}
+	if diagnostic.Code != nil {
+		if value, ok := diagnostic.Code.Value.(string); ok {
+			switch value {
+			case "ConsistentInstructionCasing":
+				return true
+			case "DuplicateStageName":
+				return true
+			case "MaintainerDeprecated":
+				return true
+			case "MultipleInstructionsDisallowed":
+				return true
+			case "NoEmptyContinuation":
+				return true
+			case "WorkdirRelativePath":
+				return true
+			}
+		}
+	}
+	return false
+}
+
 func (c *BuildKitDiagnosticsCollector) CollectDiagnostics(source, workspaceFolder string, doc document.Document, text string) []protocol.Diagnostic {
 	diagnostics, _ := parse(workspaceFolder, source, doc.(document.DockerfileDocument), text)
+	if RemoveOverlappingIssues {
+		filtered := []protocol.Diagnostic{}
+		for i := range diagnostics {
+			if !shouldIgnore(diagnostics[i]) {
+				filtered = append(filtered, diagnostics[i])
+			}
+		}
+		return filtered
+	}
 	return diagnostics
 }