From 26029962967372edf61cc558da33604cab684796 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Thu, 30 Jan 2025 19:29:49 +0100 Subject: [PATCH] chore: document printers --- pkg/printers/checkstyle.go | 40 +++++++-------- pkg/printers/codeclimate.go | 38 ++++++++------- pkg/printers/html.go | 2 + pkg/printers/json.go | 3 +- pkg/printers/junitxml.go | 60 ++++++++++++----------- pkg/printers/sarif.go | 97 +++++++++++++++++++------------------ pkg/printers/tab.go | 1 + pkg/printers/teamcity.go | 3 +- pkg/printers/text.go | 1 + 9 files changed, 131 insertions(+), 114 deletions(-) diff --git a/pkg/printers/checkstyle.go b/pkg/printers/checkstyle.go index e32eef7f51f5..0d0a83fdf200 100644 --- a/pkg/printers/checkstyle.go +++ b/pkg/printers/checkstyle.go @@ -14,25 +14,8 @@ import ( const defaultCheckstyleSeverity = "error" -type checkstyleOutput struct { - XMLName xml.Name `xml:"checkstyle"` - Version string `xml:"version,attr"` - Files []*checkstyleFile `xml:"file"` -} - -type checkstyleFile struct { - Name string `xml:"name,attr"` - Errors []*checkstyleError `xml:"error"` -} - -type checkstyleError struct { - Column int `xml:"column,attr"` - Line int `xml:"line,attr"` - Message string `xml:"message,attr"` - Severity string `xml:"severity,attr"` - Source string `xml:"source,attr"` -} - +// Checkstyle prints issues in the Checkstyle format. +// https://checkstyle.org/config.html type Checkstyle struct { w io.Writer } @@ -93,3 +76,22 @@ func (p Checkstyle) Print(issues []result.Issue) error { return nil } + +type checkstyleOutput struct { + XMLName xml.Name `xml:"checkstyle"` + Version string `xml:"version,attr"` + Files []*checkstyleFile `xml:"file"` +} + +type checkstyleFile struct { + Name string `xml:"name,attr"` + Errors []*checkstyleError `xml:"error"` +} + +type checkstyleError struct { + Column int `xml:"column,attr"` + Line int `xml:"line,attr"` + Message string `xml:"message,attr"` + Severity string `xml:"severity,attr"` + Source string `xml:"source,attr"` +} diff --git a/pkg/printers/codeclimate.go b/pkg/printers/codeclimate.go index 49b59f8e3c77..b4d94494bfcb 100644 --- a/pkg/printers/codeclimate.go +++ b/pkg/printers/codeclimate.go @@ -10,23 +10,8 @@ import ( const defaultCodeClimateSeverity = "critical" -// CodeClimateIssue is a subset of the Code Climate spec. -// https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types -// It is just enough to support GitLab CI Code Quality. -// https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format -type CodeClimateIssue struct { - Description string `json:"description"` - CheckName string `json:"check_name"` - Severity string `json:"severity,omitempty"` - Fingerprint string `json:"fingerprint"` - Location struct { - Path string `json:"path"` - Lines struct { - Begin int `json:"begin"` - } `json:"lines"` - } `json:"location"` -} - +// CodeClimate prints issues in the Code Climate format. +// https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md type CodeClimate struct { w io.Writer @@ -44,7 +29,7 @@ func (p CodeClimate) Print(issues []result.Issue) error { codeClimateIssues := make([]CodeClimateIssue, 0, len(issues)) for i := range issues { - issue := &issues[i] + issue := issues[i] codeClimateIssue := CodeClimateIssue{} codeClimateIssue.Description = issue.Description() @@ -63,3 +48,20 @@ func (p CodeClimate) Print(issues []result.Issue) error { return json.NewEncoder(p.w).Encode(codeClimateIssues) } + +// CodeClimateIssue is a subset of the Code Climate spec. +// https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types +// It is just enough to support GitLab CI Code Quality. +// https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format +type CodeClimateIssue struct { + Description string `json:"description"` + CheckName string `json:"check_name"` + Severity string `json:"severity,omitempty"` + Fingerprint string `json:"fingerprint"` + Location struct { + Path string `json:"path"` + Lines struct { + Begin int `json:"begin"` + } `json:"lines"` + } `json:"location"` +} diff --git a/pkg/printers/html.go b/pkg/printers/html.go index 7dd1e5c623d0..6fc6bc62a2b8 100644 --- a/pkg/printers/html.go +++ b/pkg/printers/html.go @@ -122,6 +122,8 @@ type htmlIssue struct { Code string } +// HTML prints issues in an HTML page. +// It uses the Cloudflare CDN (cdnjs) and React. type HTML struct { w io.Writer } diff --git a/pkg/printers/json.go b/pkg/printers/json.go index 28509cac459b..f2f8f11c5567 100644 --- a/pkg/printers/json.go +++ b/pkg/printers/json.go @@ -8,8 +8,9 @@ import ( "github.com/golangci/golangci-lint/pkg/result" ) +// JSON prints issues in a JSON representation. type JSON struct { - rd *report.Data // TODO(ldez) should be drop in v2. Only use by JSON reporter. + rd *report.Data w io.Writer } diff --git a/pkg/printers/junitxml.go b/pkg/printers/junitxml.go index 7d0a703b0a5e..46ffc22bb058 100644 --- a/pkg/printers/junitxml.go +++ b/pkg/printers/junitxml.go @@ -12,34 +12,10 @@ import ( "github.com/golangci/golangci-lint/pkg/result" ) -type testSuitesXML struct { - XMLName xml.Name `xml:"testsuites"` - TestSuites []testSuiteXML -} - -type testSuiteXML struct { - XMLName xml.Name `xml:"testsuite"` - Suite string `xml:"name,attr"` - Tests int `xml:"tests,attr"` - Errors int `xml:"errors,attr"` - Failures int `xml:"failures,attr"` - TestCases []testCaseXML `xml:"testcase"` -} - -type testCaseXML struct { - Name string `xml:"name,attr"` - ClassName string `xml:"classname,attr"` - Failure failureXML `xml:"failure"` - File string `xml:"file,attr,omitempty"` - Line int `xml:"line,attr,omitempty"` -} - -type failureXML struct { - Message string `xml:"message,attr"` - Type string `xml:"type,attr"` - Content string `xml:",cdata"` -} - +// JunitXML prints issues in the Junit XML format. +// There is no official specification for the JUnit XML file format, +// and various tools generate and support different flavors of this format. +// https://github.com/testmoapp/junitxml type JunitXML struct { extended bool w io.Writer @@ -97,3 +73,31 @@ func (p JunitXML) Print(issues []result.Issue) error { } return nil } + +type testSuitesXML struct { + XMLName xml.Name `xml:"testsuites"` + TestSuites []testSuiteXML +} + +type testSuiteXML struct { + XMLName xml.Name `xml:"testsuite"` + Suite string `xml:"name,attr"` + Tests int `xml:"tests,attr"` + Errors int `xml:"errors,attr"` + Failures int `xml:"failures,attr"` + TestCases []testCaseXML `xml:"testcase"` +} + +type testCaseXML struct { + Name string `xml:"name,attr"` + ClassName string `xml:"classname,attr"` + Failure failureXML `xml:"failure"` + File string `xml:"file,attr,omitempty"` + Line int `xml:"line,attr,omitempty"` +} + +type failureXML struct { + Message string `xml:"message,attr"` + Type string `xml:"type,attr"` + Content string `xml:",cdata"` +} diff --git a/pkg/printers/sarif.go b/pkg/printers/sarif.go index 8b1dd2ee29ea..5f955a0560b0 100644 --- a/pkg/printers/sarif.go +++ b/pkg/printers/sarif.go @@ -12,53 +12,9 @@ const ( sarifSchemaURI = "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.6.json" ) -type SarifOutput struct { - Version string `json:"version"` - Schema string `json:"$schema"` - Runs []sarifRun `json:"runs"` -} - -type sarifRun struct { - Tool sarifTool `json:"tool"` - Results []sarifResult `json:"results"` -} - -type sarifTool struct { - Driver struct { - Name string `json:"name"` - } `json:"driver"` -} - -type sarifResult struct { - RuleID string `json:"ruleId"` - Level string `json:"level"` - Message sarifMessage `json:"message"` - Locations []sarifLocation `json:"locations"` -} - -type sarifMessage struct { - Text string `json:"text"` -} - -type sarifLocation struct { - PhysicalLocation sarifPhysicalLocation `json:"physicalLocation"` -} - -type sarifPhysicalLocation struct { - ArtifactLocation sarifArtifactLocation `json:"artifactLocation"` - Region sarifRegion `json:"region"` -} - -type sarifArtifactLocation struct { - URI string `json:"uri"` - Index int `json:"index"` -} - -type sarifRegion struct { - StartLine int `json:"startLine"` - StartColumn int `json:"startColumn"` -} - +// Sarif prints issues in the SARIF format. +// https://sarifweb.azurewebsites.net/ +// https://docs.oasis-open.org/sarif/sarif/v2.1.0/ type Sarif struct { w io.Writer } @@ -115,3 +71,50 @@ func (p Sarif) Print(issues []result.Issue) error { return json.NewEncoder(p.w).Encode(output) } + +type SarifOutput struct { + Version string `json:"version"` + Schema string `json:"$schema"` + Runs []sarifRun `json:"runs"` +} + +type sarifRun struct { + Tool sarifTool `json:"tool"` + Results []sarifResult `json:"results"` +} + +type sarifTool struct { + Driver struct { + Name string `json:"name"` + } `json:"driver"` +} + +type sarifResult struct { + RuleID string `json:"ruleId"` + Level string `json:"level"` + Message sarifMessage `json:"message"` + Locations []sarifLocation `json:"locations"` +} + +type sarifMessage struct { + Text string `json:"text"` +} + +type sarifLocation struct { + PhysicalLocation sarifPhysicalLocation `json:"physicalLocation"` +} + +type sarifPhysicalLocation struct { + ArtifactLocation sarifArtifactLocation `json:"artifactLocation"` + Region sarifRegion `json:"region"` +} + +type sarifArtifactLocation struct { + URI string `json:"uri"` + Index int `json:"index"` +} + +type sarifRegion struct { + StartLine int `json:"startLine"` + StartColumn int `json:"startColumn"` +} diff --git a/pkg/printers/tab.go b/pkg/printers/tab.go index c6d390d188cf..04260e09deb7 100644 --- a/pkg/printers/tab.go +++ b/pkg/printers/tab.go @@ -11,6 +11,7 @@ import ( "github.com/golangci/golangci-lint/pkg/result" ) +// Tab prints issues using tabulation as field separator. type Tab struct { printLinterName bool useColors bool diff --git a/pkg/printers/teamcity.go b/pkg/printers/teamcity.go index 83c4959114f4..b7ef09af56f0 100644 --- a/pkg/printers/teamcity.go +++ b/pkg/printers/teamcity.go @@ -14,7 +14,8 @@ const ( largeLimit = 4000 ) -// TeamCity printer for TeamCity format. +// TeamCity prints issues in the TeamCity format. +// https://www.jetbrains.com/help/teamcity/service-messages.html type TeamCity struct { w io.Writer escaper *strings.Replacer diff --git a/pkg/printers/text.go b/pkg/printers/text.go index 56cced769695..7d41943b4fea 100644 --- a/pkg/printers/text.go +++ b/pkg/printers/text.go @@ -11,6 +11,7 @@ import ( "github.com/golangci/golangci-lint/pkg/result" ) +// Text prints issues with a human friendly representation. type Text struct { printIssuedLine bool printLinterName bool